feedback

feedback · Capture framework friction — a sixty-second detour, then back to work

A cross-cutting activity (prefix-less, like status): the capture half of the framework's dogfood→distill→upstream loop (shared/feedback-loop.md — read it once; this skill is its clerical arm). You run in a consumer repo. The finding you write here is triaged later in the framework's master repo — you never fix vendored files yourself (upstream-first).

The one routing test — before writing anything

Where would the fix land?

• In the vendored framework (.agents/skills/**, .claude/skills/**, shared/**, tools/vendor.py, a gate/template/protocol) → this skill. Continue below.
• In this project's own code or realizations → a product bug: the normal chain owns it (/05-reviewer findings → /04-builder), not the ledger.
• In this project's spine (a requirement/constraint is wrong) → the amendment protocol (shared/spec-amendment-protocol.md), not the ledger.
• Genuinely unsure → ledger it (severity: friction-only, say so in actual:) — a mis-filed entry costs one triage minute; a lost one costs the fix.

The procedure (do all five, in order)

1. Stamp. Read source_commit from .director/vendor-manifest.json. Absent/unreadable → use unknown (pre-manifest vendor) and note that a re-sync will fix stamping.
2. Number. Read docs/framework-feedback.md; next id = max(FB-NNN) + 1, zero-padded (none yet → FB-001). If the ledger file itself is absent, create it first from the template in shared/feedback-loop.md §1.
3. Fill the entry — every field, per the ledger's own template: framework: (the SHA from step 1) · harness: (the one you are running on: claude-code | codex | gemini-cli) · seat: (00-discovery … status, or shared / vendor) · severity: (blocks-gate — a gate/verdict was wrong or unreachable · wrong-but-recoverable — incorrect output you corrected · friction-only — worked, but cost real time) · expected: / actual: (the load-bearing pair — a mood is not a finding) · repro: (minimal steps or the exact command) · artifact: (the transcript / diff / report path that shows it) · status: open.
4. Append the entry to the end of docs/framework-feedback.md. Append-only: never edit or renumber an existing entry (supersede with a new one that names it), never compact the ledger. (2026-07-28) The status: line is the one exception, and it is not yours to write. The master repo sets it at sync time — resolved-in <sha>, or deferred-in <sha> (trigger: …) when triage acknowledged the entry but did not action it, sometimes with a landed-as: line when the fix differed from what you proposed. So: a deferred-in entry is not ignored — keep your workaround until its stated trigger fires; and an entry still reading open after a sync means it was not disposed, which is worth raising. Never set your own status beyond the initial open.
5. Confirm + resume. Tell the user the id (logged FB-007) in one line and return to the interrupted work — this skill is a detour, never a takeover. If you hot-patched a vendored file to unblock (the emergency escape hatch), the entry is blocks-gate and actual: describes the patch.