idd-issue Step 5: add CI/loop hard-parse warning for echo expansion (parallel to --no-multi-finding warning)

[kiki830621]

Problem

Source: surfaced during /idd-verify --pr 104 Codex review of #103 (regression note, INFO severity).
Full verify report: #104 (comment)

#103 PR #104 expanded idd-issue Step 5 prose: previously only output issue number / URL / labels / type metadata; now also echoes the AI-rendered ## Type / ## Expected / ## Actual + plain-language interpretation (per F1 NSQL run → report).

For human readers this is strictly better — misparse is catchable without opening the issue URL.

For CI / /loop scripts that hard-parse Step 5 terminal prose, this is a silent surface change.

idd-issue already has one CI-caller warning (v2.55.0 multi-finding auto-trigger): skills/idd-issue/SKILL.md:994 warns "automated / CI / /loop callers expecting the pre-v2.55.0 always-single-issue behavior of idd-issue source.docx MUST pass --no-multi-finding explicitly". The v2.64.0 Step 5 echo expansion lacks an analogous warning.

Type

documentation

Expected

skills/idd-issue/SKILL.md Step 5 has a ⚠️ note for CI/loop callers, mirroring the v2.55.0 multi-finding warning shape:

> ⚠️ **CI / `/loop` callers (v2.64.0+)**: Step 5 terminal output expanded from
> metadata-only (`number / URL / labels / type`) to also echoing the rendered
> `## Type` / `## Expected` / `## Actual` + plain-language interpretation.
> If your script hard-parses Step 5 output for the metadata fields only,
> add a `-m 1` / first-N-lines guard or grep specifically for the
> `issue.*#NNN.*created` line — the new echo paragraphs follow it.

Actual

No warning. CI/loop scripts that did idd-issue ... | grep '^Issue #' or similar still work (the metadata line is preserved at the top); but scripts that did idd-issue ... | tail -1 or naively parse the full output will see the new echo content mixed in.

The likelihood of breakage is low — most CI parsers anchor on the URL line. The cost of adding the warning is one paragraph. Defensive documentation, mirroring an existing precedent.

Impact

• Affected surfaces: skills/idd-issue/SKILL.md Step 5 (one ⚠️ block addition)
• Reference: existing precedent at skills/idd-issue/SKILL.md:994 (the v2.55.0 multi-finding CI warning)
• Verification: regression-test idd-all and idd-all-chain parsers — neither should rely on Step 5 prose (both consume the issue number from the URL line).

Not blocking #103's close. Doc-polish follow-up.

Current Status

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

Key Decisions

• Complexity = Simple (Layer V: V≤3, untriggered)
• Strategy: 1 bullet (insert ⚠️ paragraph in idd-issue Step 5 with verbatim wording from issue body)
• Layer 1 disqualifier hit: primary deliverable is updating existing prose without changing behavior
• Sister concerns: none surfaced
• Residue: (none)

Scope Changes

• (none — diagnosed scope matches issue body)

Blocking

• (none — ready for /idd-implement idd-issue Step 5: add CI/loop hard-parse warning for echo expansion (parallel to --no-multi-finding warning) #107)

Commits

• (none yet)

[kiki830621]

Diagnosis

Type

documentation — single-paragraph addition to idd-issue/SKILL.md Step 5.

Analysis

#103 PR #104 expanded idd-issue Step 5 terminal prose from metadata-only (number / URL / labels / type) to also echo the AI-rendered ## Type / ## Expected / ## Actual + plain-language interpretation (NSQL run → report doctrine). For humans this is strictly better — misparse becomes catchable from the terminal without opening the issue URL.

For CI / /loop parsers that consume Step 5 stdout, this is a silent surface change. The existing v2.55.0 multi-finding warning at skills/idd-issue/SKILL.md:994 documents a precedent for warning CI callers of behavior changes in idd-issue's terminal output — that warning specifically mentions the --no-multi-finding flag. The Step 5 echo expansion has no analogous warning yet.

Issue body specifies the exact paragraph text to add. The fix is a single Edit in one file.

Impact

• Affected files: plugins/issue-driven-dev/skills/idd-issue/SKILL.md (one ⚠️ paragraph at Step 5)
• Affected user flow: none (purely documentation; existing behavior unchanged)
• No CHANGELOG / version bump needed: docs polish only, not a behavior change

Strategy

• Insert ⚠️ paragraph in idd-issue/SKILL.md Step 5: place after the "回顯 render 的詮釋" block, before the "下一步" pointer. Use the exact wording from the issue body's ## Expected section:

  > ⚠️ **CI / `/loop` callers (v2.64.0+)**: Step 5 terminal output expanded from
  > metadata-only (`number / URL / labels / type`) to also echoing the rendered
  > `## Type` / `## Expected` / `## Actual` + plain-language interpretation.
  > If your script hard-parses Step 5 output for the metadata fields only,
  > add a `-m 1` / first-N-lines guard or grep specifically for the
  > `issue.*#NNN.*created` line — the new echo paragraphs follow it.
  

Complexity

Simple — triggers Layer 1 disqualifier:

Primary deliverable is updating existing prose without changing behavior (typo, wording cleanup, restructuring documents)

The fix is a single Edit, single file, single paragraph; no behavior change in idd-issue. Layer 1 hits → forced Simple, skip Layer 2/3/P/V.

Risks

• Wording fidelity: paragraph text quoted from issue body is the canonical text. Verbatim copy avoids drift.
• Placement: must be after the v2.64.0 echo paragraph (otherwise the warning precedes the feature it's warning about and reads awkward). Mitigation: place anchor is "after the > 為什麼 reason block, before 提示下一步".
• Lining up with existing v2.55.0 precedent: the v2.55.0 multi-finding warning is at line 994; this new warning should be near it OR at Step 5 itself. Most-natural location: at Step 5 directly (where the echo is described) — keeps reader context. Precedent location at line 994 is also near Step 5.

Residue

(none) — issue scope is fully operationalizable. The deeper concern of "how to systematically detect CI-caller breakage across all idd-* skills, not just idd-issue Step 5" is real but out of scope here (#108 partially addresses it for PR-body templates; a general pattern would be a separate Plan-tier issue).

Vagueness Pre-check

• V1: 1 — exact paragraph text quoted verbatim in ## Expected — completely unambiguous what to insert.
• V4: 2 — completion = paragraph appears in idd-issue/SKILL.md Step 5; single Edit, single file.
• Triggered: no — both axes ≤ 3

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

none surfaced — single-paragraph docs addition; the deeper question ("systematic CI-caller breakage detection across all idd-* skills") is captured in Residue, not as a sister.

[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-issue/SKILL.md Step 5 — added ⚠ paragraph for CI/loop hard-parse warning (verbatim wording from issue body) → 51373fc

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

Changes

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

Scope Compliance

On-plan — single-paragraph addition to one file. Layer 1 disqualifier hit (prose update, no behavior change). Anchor: placed after the v2.64.0 echo paragraph (where the feature being warned about lives), before the next-step pointer. Wording verbatim from issue body's ## Expected section. Mirrors the v2.55.0 --no-multi-finding CI warning precedent.

Sister Bugs Filed (mid-impl, Step 5.7)

none surfaced — single-paragraph docs add is self-contained.

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

#103 PR #104 expanded idd-issue Step 5 from metadata-only stdout (number / URL / labels / type) to also echo the rendered ## Type / ## Expected / ## Actual + plain-language interpretation (per NSQL run → report doctrine: report what AI made, not just where it lives). Strictly better for interactive human readers — misparse becomes catchable from the terminal without clicking through to GitHub. But it's a silent surface change for CI scripts and /loop callers that hard-parse Step 5 stdout — they were getting predictable line counts and now get unpredictably-extended output.

Root Cause

#103's scope reasonably focused on the human-readability win and did not enumerate downstream consumers. No precedent in the skill for documenting "behavior change for automated callers" beyond the v2.55.0 --no-multi-finding CI warning block.

Solution

skills/idd-issue/SKILL.md Step 5 adds one ⚠ paragraph between the v2.64.0 echo block (> 為什麼 paragraph) and the 提示下一步 pointer. Anchored where CI authors actually read when troubleshooting Step 5 output. Mirrors the v2.55.0 --no-multi-finding CI warning precedent shape — same ⚠ marker, same blockquote format, same "(parallel precedent)" parenthetical (no specific line number — paths rot).

Wording is near-verbatim per the issue body's ## Expected block, with two skill-internal additions: the #107 self-reference suffix and the precedent parenthetical. CHANGELOG entry softened from "Verbatim" to "near-verbatim ... with two skill-internal additions" per Codex review (#110 verify).

Pure defensive documentation: no behavior change, no new code path, no skill internals touched. The kind of surface notice that's cheap to add and saves "why did my CI suddenly start parsing wrong" debugging.

Verification

6-AI verify ensemble (PR #110 cluster mode) — verify-gated PASS. Master: #110 (comment). Per-issue verdict for #107: requirements PASS (correct anchor + wording), logic PASS, security 0 findings (pure prose). Off-by-2 line number reference ("below at line 994" → actual 996) caught by regression reviewer and dropped in fix commit 6bae8e6 — descriptive "below" suffices.

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-issue/SKILL.md Step 5 ⚠ paragraph + shared CHANGELOG.md + plugin.json (2.65.0 → 2.66.0)

Residue Acknowledgement

(none) — Diagnosis Residue was (none). Step 3.6 dogfooded silent-skip path on this issue's close too.