--- name: deft-directive-feedback description: >- Mid-session and session-end framework-gap escalation for directive consumers. Collects friction/gap reports, drafts deduped framework-gap issues against deftai/directive, and files upstream only after explicit operator confirmation. Use when the operator says "file a directive issue", "file this upstream", or "report a framework gap". --- # Deft Directive Feedback -- gap escalation to upstream Conversational batched flow for filing framework gaps discovered during consumer sessions. Mirrors the confirmation gate from `deft-directive-article-review` -- the agent drafts and dedups; the operator approves before any upstream issue is created. House style for title/body/labels/dedup lives in [`docs/framework-gap-filing.md`](../../docs/framework-gap-filing.md). Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY. ## When to Use - Mid-session when the operator says "file a directive issue", "file this upstream", "report a framework gap", or "directive feedback" -- even while `plan.policy.valueFeedback.upstreamPrompt` is OFF - Session end when `friction:*` ledger signals or the operator reports a directive shortfall - After the operator opts into upstream filing via the audited setter below ## Preconditions - ! Run only from a **consumer project** -- the filing path no-ops inside the directive maintainer repo - ! Filing requires `plan.policy.valueFeedback.upstreamPrompt` ON. If OFF, draft with `deft feedback:file --dry-run` / `--json` (title+body still print), then ask the operator to enable via `deft policy:enable-value-feedback --confirm --upstream-prompt`. If declined, STOP safely -- do not hand-edit PROJECT-DEFINITION. - ! Inspect current state with `deft policy:show --field=valueFeedback` - ⊗ File upstream issues without explicit operator confirmation - ⊗ Treat handwritten typed-block / PROJECT-DEFINITION edits as the primary audited setter ## Phase 1 -- Collect (batched) - ! Gather concrete gap reports from the session: what was expected, what happened, and minimal reproduction context - ! Batch multiple friction items into one upstream issue when they share a root cause; otherwise prepare separate drafts - ~ Prefer attributed phrasing ("encoding gate blocked a valid file") over vague quality claims - ! Follow [`docs/framework-gap-filing.md`](../../docs/framework-gap-filing.md) for title/BLOCKER, section shape, empty create labels, privileged `adoption-blocker`, dedup, and Refs ## Phase 1.5 -- Adoption-blocker judgment - ! Ask whether the gap blocks adoption. A gap blocks adoption when the consumer cannot complete an intended Directive flow and has no reasonable workaround. - ! When the answer is yes, collect the body evidence a privileged actor needs before applying `adoption-blocker`: affected consumer flow and version; documented alternatives attempted, or why they are not a reasonable workaround; observed recovery cost. Pass `--blocker` (and `--flow`, `--alternatives`, `--recovery-cost` when known) so the title carries `BLOCKER` and the body carries those sections. - ! When the answer is no or unknown, omit `--blocker`. Absence of the token does not mean "not a blocker" -- it means not classified. - ⊗ Apply or request the `adoption-blocker` ranking label from a consumer-authored title. The label is a privileged write after the body-evidence test. ## Phase 2 -- Draft + dedup - ! For each candidate report, run a dry draft (reuse the same report fields and target repo in Phase 3; confirmation adds `--confirm` and drops `--dry-run`/`--json`): ```bash deft feedback:file --summary "" --context "" --expected "" --actual "" --notes "" [--blocker --flow "" --alternatives "" --recovery-cost ""] [--dry-run|--json] ``` - ! Read the printed draft title/body with the operator before proceeding - ! If the command reports a duplicate open issue, STOP and link the existing issue instead of filing again - ⊗ Proceed past a duplicate-detection block without operator override - ~ When go-task is installed, the Taskfile may wrap the same verb; prefer `deft feedback:file` as primary ## Phase 3 -- Confirm + file - ! Present the final draft and ask for explicit yes/no confirmation - ! Only after approval, re-run the **same report fields and target repo** with `--confirm` added and without `--dry-run` or `--json`: ```bash deft feedback:file --summary "" --context "" --expected "" --actual "" --confirm [--blocker] ``` - ! Print the filed issue URL to the operator - ⊗ Use `Closes`/`Fixes`/`Resolves` in the upstream body -- use `Refs #1709` only ## Phase 4 -- Handoff - ~ Record the upstream issue URL in the session handoff or continue checkpoint if the operator tracks follow-ups locally - ~ Return to the prior workflow; gap escalation does not block story completion ## Anti-Patterns - ⊗ Filing from the maintainer framework repo (consumer-only guard) - ⊗ Skipping dedup review when the command reports an existing open issue - ⊗ Treating `--confirm` as implicit from broad session approval -- require an explicit filing confirmation step - ⊗ Infer "not a blocker" from an unmarked report -- absence of `BLOCKER` means not classified - ⊗ Auto-apply `adoption-blocker` from a consumer-authored title - ⊗ Hand-editing PROJECT-DEFINITION to flip `upstreamPrompt` instead of the audited setter