idd-close: Residue acknowledgement prompt — close the F3 write-only loop

[kiki830621]

Problem

Source: surfaced during /idd-verify --pr 104 Devil's Advocate review of #103 (Finding D2, INFO severity).
Full verify report: #104 (comment)

#103 added ### Residue to the Diagnosis report template (NSQL §4.6 — non-operationalizable intent / horizon). Producer: idd-diagnose Step 3 template. Consumer: nobody.

Verified via grep of skills/idd-*/SKILL.md — idd-implement / idd-verify / idd-close / idd-list / idd-update / idd-all all read other Diagnosis sections (Strategy / Risks / Complexity / Implementation Complete) but none read ### Residue.

In v2.64.0, Residue is write-only: AI writes it during diagnose, nobody reads it during implement/verify/close.

Type

enhancement (latent ritual-drift risk)

Expected

Residue has a downstream consumer that pressures it to stay honest. Specifically: idd-close reads ### Residue from the latest Diagnosis comment and prompts the user — "Did any residue become operationalizable during this work? If so, file as new issue."

This closes the loop: residue declared at diagnosis time becomes either (a) acknowledged still-residue at close, or (b) a follow-up issue filed because the work surfaced an angle for it.

Actual

### Residue is declared at diagnosis and silently buried. No skill ever asks "what happened to it?". A future maintainer reading a closed issue can't tell whether the residue was deliberately deferred or just forgotten.

Impact

• Affected surfaces: skills/idd-close/ (new prompt at close time)
• Related: PR IDD human-in-the-loop should conform to the NSQL confirmation protocol (v4.1.0) #104 closes IDD human-in-the-loop should conform to the NSQL confirmation protocol (v4.1.0) #103 with this gap acknowledged
• Reference: NSQL §4.6 (kiki830621/NSQL)
• Devil's Advocate's exact phrasing: "latent capacity for the section to drift into ritual filler with no consumer pressure to keep it honest"

Not blocking #103's close. SHOULD-tier add: residue acknowledgement at close-time.

Current Status

Phase: diagnosed
Last updated: 2026-05-20 by idd-diagnose

Key Decisions

• Complexity = Plan (Layer V: V≤3, untriggered)
• Strategy: 6 bullets covering new idd-close step + AskUserQuestion + audit trail
• Plan-tier triggers: decision-heavy (4 design questions), close-time deliberation boundary, 2+ file sequence dependency
• Sister concerns: none surfaced
• Residue: per-issue residue granularity question (out of idd-close: Residue acknowledgement prompt — close the F3 write-only loop #105 scope)

Scope Changes

• (none — diagnosed scope matches issue body)

Blocking

• (none — ready for /idd-plan idd-close: Residue acknowledgement prompt — close the F3 write-only loop #105 (per chain shell unattended, idd-plan EnterPlanMode auto-applies))

Commits

• (none yet)

[kiki830621]

Diagnosis

Type

feature (enhancement) — close the F3 ### Residue write-only loop introduced in #103 v2.64.0.

Analysis

### Residue was added to the Diagnosis report template per NSQL §4.6 as the place to mark issue intent that cannot be operationalized (purpose / horizon, distinct from Layer V vagueness). The producer side (idd-diagnose Step 3 template) was shipped in 4aef425. The consumer side was never implemented:

• idd-implement reads Strategy / Risks / Complexity — not Residue
• idd-verify reads diff + verify findings — not Residue
• idd-close reads Implementation Complete Checklist (gate logic) — not Residue
• idd-list / idd-update / idd-all — none read Residue

Per Devil's Advocate D2 in PR #104 verify: "latent capacity for the section to drift into ritual filler with no consumer pressure to keep it honest." The doctrine value of Residue ("mark, never silently drop") collapses if nothing downstream ever asks "what happened to it?" — over time it becomes ignored boilerplate.

The fix surface is idd-close: it is the lifecycle moment where the user re-reads the issue's whole arc, so it is the natural place to ask "did residue become operationalizable during the work, or is it still residue?".

Impact

• Affected files: plugins/issue-driven-dev/skills/idd-close/SKILL.md (new step), plugins/issue-driven-dev/CHANGELOG.md, plugins/issue-driven-dev/.claude-plugin/plugin.json.
• Affected user flow: at /idd-close time, an extra deliberation moment that fires only when the latest Diagnosis comment has a non-empty ### Residue section.

Strategy

• New idd-close step (numbering TBD in plan — likely Step 3.6 between Step 3.5 keyword scan and Step 4 publish+close) — read latest ## Diagnosis comment, extract ### Residue section content
• Branch on Residue content:
  • (none) or section missing → silent skip + audit trail line no residue declared at diagnose time
  • non-empty content → AskUserQuestion (IC_R011 canonical 3-option pattern): file as follow-up issue(s) now / still residue (acknowledge, no new issue) / skip — record in audit trail only
• File issues (if user picks file): loop gh issue create per residue item with body containing **Source**: residue from #$NNN at /idd-close time for traceability
• Audit trail PATCH: append ### Residue Acknowledgement section to closing comment per canonical heading conventions (Filed: #X, #Y / Acknowledged as still residue (text quoted) / Skipped per user choice)
• Step 0.5 bootstrap: add residue_acknowledgement TaskCreate entry alongside closing_followup_keyword_scan
• CHANGELOG entry under [Unreleased]
• Plugin version bump: minor (additive close-time step)

Complexity

Plan — triggered by Layer P signals:

• Decision-heavy: 2+ design questions need resolution before code — (1) exact placement (before/after Step 3.5 keyword scan?), (2) AskUserQuestion default option choice, (3) how to handle multi-item residue ("file all" vs per-item picker), (4) whether to PATCH the original Diagnosis comment vs only append to closing summary
• Touches risk-sensitive boundary: close-time deliberation — same lifecycle gate as Step 0 structural / Step 1.6 semantic; getting wording wrong creates friction across every future close
• 2+ files with sequence dependency: idd-close SKILL.md + CHANGELOG + plugin.json must land together; SKILL.md change must be done before EnterPlanMode review (Plan-tier discipline)

Risks

• Edge case: multiple Diagnosis comments (re-diagnosed after clarification) — must use latest by createdAt desc (precedent in Step 0 supersession). If older Diagnosis has residue but latest doesn't, latest wins → could "lose" residue from earlier draft. Mitigation: only scan latest, document that.
• Edge case: legacy issue (no ### Residue section at all) — pre-v2.64.0 diagnoses won't have this section. Behavior: silent skip + audit trail line no Residue section in Diagnosis (pre-v2.64.0 format).
• Step 6.5 ordering: Step 6.5 Distribution Sync also PATCHes closing comment. Both steps must use the same patch_closing_comment_append helper to avoid race / overwrites. Already documented contract — sister concern minimal.
• AskUserQuestion friction at close time: closing already has Step 1.6 semantic-gate AskUserQuestion (warn) + Step 3.5 keyword scan AskUserQuestion. Adding a 3rd AskUserQuestion at close risks ceremony-fatigue. Mitigation: silent skip when residue is (none) (which is the common case for clear-scope issues).

Residue

Closing the F3 write-only loop is a structural fix (give Residue a consumer). It does not address the question of whether the residue field is the right tool for what it claims to track — there might be intents that span multiple issues / multiple work sessions, for which a single issue's residue is too narrow. This deeper question (is per-issue residue the right granularity?) cannot be operationalized via the idd-close step alone — it would require redesigning how IDD tracks "purpose / horizon" across multiple issues, which is out of scope here.

Vagueness Pre-check

• V1: 2 — issue body has clear ## Expected statement specifying the residue-acknowledgement prompt; Strategy lists 6 specific bullets.
• V4: 3 — acceptance is mostly clear (residue gets file/acknowledge/skip + audit trail) but exact AskUserQuestion default + placement are Plan-tier deliberation points.
• Triggered: no — both axes ≤ 3

Sister Concerns Filed (mid-diagnose, v2.47.0+ #528)

none surfaced — Diagnosis scope is tight (single skill, single new step); related Step 6.5 audit-trail PATCH helper is already documented contract, not a sister concern.

[kiki830621]

Implementation Complete

PR: TBD (cluster — Phase 3 next) · branch idd/chain-multi-5439e76b-idd-close-residue-acknowledgement-prompt

Checklist (synced from TaskList)

• plugins/issue-driven-dev/skills/idd-close/SKILL.md — NEW Step 3.6 Residue Acknowledgement between Step 3.5 keyword scan and Step 4 publish+close → c9cfa59
• Step 0.5 Bootstrap Task List entry residue_acknowledgement → c9cfa59
• AskUserQuestion 3-option (still residue / file follow-up / skip) per IC_R011 canonical pattern → c9cfa59
• Silent skip conditions: section missing, content (none), pre-v2.64.0 format → c9cfa59
• Audit trail PATCH 5 branches (all outcomes covered) → c9cfa59
• Manifest helper integration for filed follow-ups when chain context active → c9cfa59
• CHANGELOG v2.66.0 entry → 0370516
• plugin.json version bump 2.65.0 → 2.66.0 → 0370516

Legend: - [x] done. idd-close will refuse to close if any - [ ] remains.

Changes

• c9cfa59 feat(idd-close): Step 3.6 Residue Acknowledgement — close F3 write-only loop (Refs idd-close: Residue acknowledgement prompt — close the F3 write-only loop #105)
• 0370516 chore: bump issue-driven-dev to v2.66.0 (cluster bump shared with idd-issue Step 5: add CI/loop hard-parse warning for echo expansion (parallel to --no-multi-finding warning) #107 + Sync 4-template PR-body checklist wording to match #102 NSQL doctrine #108)

Scope Compliance

On-plan — exactly the diagnosis Strategy bullets. New idd-close Step 3.6 mirrors Step 3.5 (closing-summary-scan) discipline; advisory not blocking per IC_R011 closure-tier eligibility; reads latest ## Diagnosis comment per Step 0 supersession discipline. Silent skip when residue is (none) keeps clear-scope issues frictionless.

Sister Bugs Filed (mid-impl, Step 5.7)

none surfaced — closing-time step addition is self-contained. Step 6.5 Distribution Sync also PATCHes closing comment via patch_closing_comment_append helper — both Step 3.6 audit PATCH (Step 4 in-memory draft) + Step 6.5 audit PATCH (post-publish comment via helper) coexist without race because they operate on different artifacts at different times.

Next: verification pending

/idd-verify --pr <PR> after cluster PR open (Phase 3 next)

[kiki830621]

Verify (PR mode, cluster) — verify-gated PASS for this issue's portion of PR #110. Findings dispatched in-PR per feedback_verify_fix_same_pr; cluster ready to merge. See master report above for per-issue verdict + fix commit 6bae8e6.

[kiki830621]

Closing Summary

Problem

idd-diagnose v2.64.0 (#103) added a mandatory ### Residue section to the Diagnosis template (NSQL §4.6 — non-operationalizable intent: the issue's purpose / horizon that cannot be reduced to function-and-argument). Producer side worked: every Diagnosis comment now carries an explicit Residue field. But the section had no downstream consumer — once a Diagnosis was posted, Residue lived in markdown forever, never re-read at close time, never required acknowledgement before the issue went to "closed". PR #104 Devil's Advocate finding D2 spelled the failure mode out: "latent capacity for the section to drift into ritual filler with no consumer pressure to keep it honest." Without a consumer, MARK-NEVER-DROP became MARK-AND-FORGET.

Root Cause

#103's scope deliberately stopped at the Diagnosis template — the design decision was "let producer-side prove value first, add consumer in a follow-up." This issue is that follow-up: needs to wire Residue into the close pathway so the issue's non-operationalizable intent gets surfaced exactly once at the deliberation moment that most matters (post-implementation, pre-close, when the residue has either been resolved-as-by-product, escaped current scope, or genuinely remained un-addressable).

Solution

skills/idd-close/SKILL.md adds Step 3.6 — Residue Acknowledgement, placed between Step 3.5 (closing follow-up keyword scan) and Step 4 (publish + close). Flow:

1. awk extraction reads the latest ## Diagnosis comment's ### Residue section (silent skip when section missing / content is (none) / pre-v2.64.0 format — backward compatible for legacy issues).
2. When residue content is non-empty, AskUserQuestion 3-option per IC_R011 canonical (acknowledge as-is / file as follow-up issue(s) / skip — record in audit trail only).
3. Audit-trail PATCH appends ### Residue Acknowledgement to the in-memory closing summary draft before Step 4 publishes — same draft, single coherent comment.
4. Filed follow-ups get spawn manifest entries when chain context is active.
5. Rollback hatch: IDD_LOW_BAR_RESIDUE_ACK=false env var silently skips checkpoint while preserving audit-trail entry.

SHOULD-tier non-blocking (per closure-tier IC_R011 eligibility — closure is mostly mechanical action with text artifact, hard-blocking on every "still residue" would impose friction beyond the value).

Step 0.5 Bootstrap adds residue_acknowledgement task entry — visible progress in TaskList per repo CLAUDE.md 鐵律.

Verification

6-AI verify ensemble (PR #110 cluster mode) — verify-gated PASS. Master report: #110 (comment). Per-issue verdict for #105: requirements / logic / security / regression / Codex all FULLY addressed; Devil's Advocate angles (Step 3.6 placement vs AskUserQuestion stacking, SHOULD vs SHALL question) dismissed as well-reasoned trade-offs.

Changes

• Squash merge: cb19802 (PR chain (multi-root): 3 issues — idd-close: Residue acknowledgement prompt — close the F3 write-only loop #110)
• Doc-only: skills/idd-close/SKILL.md + shared CHANGELOG.md + plugin.json (2.65.0 → 2.66.0 minor)

Residue Acknowledgement

(none) — Diagnosis comment's Residue was (none). Step 3.6 dogfooded on its own closing: scanned Diagnosis, found (none), silent-skipped per the new contract.