Plan: Add rejection remediation prompt to plan-review-agents

Context

The plan-review-agents skill produces a 15-section report with a final decision of Approve, Approve with revisions, or Reject. Currently all three outcomes follow the same code path — section 14 states the verdict in one line plus a rationale sentence. When a plan is rejected, the user must manually cross-reference sections 3 (highest-risk issues), 4 (blocking issues), and 12 (recommended changes) to understand what went wrong and what to fix. There is no actionable, consolidated output for rejection.

The project uses a “self-contained prompt” pattern in plan Next Steps sections: a label followed by a fenced ```text block containing a standalone prompt a user can copy-paste into Claude. This feature brings that pattern into the review panel’s rejection output.

A stress test of the initial design surfaced three high-severity gaps and several medium/low issues that this revised plan addresses:

• Re-run loop breakage — Step 7 always appends a ## Panel Review section. On re-run after fixing a rejected plan, reviewers read their own old review and a second Panel Review gets appended. No handling exists for pre-existing panel review sections.
• Background mode framing — “Paste into Claude” is wrong when the background agent is Claude. The prompt needs context-aware framing.
• Triple-nested fences — The output template wraps the report in a 3-backtick ```markdown fence. Adding an inner ```text block breaks CommonMark parsing. The outer fence must be widened to 5 backticks.

Objective

Extend section 14 of the plan-review-agents report with decision-specific output:

• Reject — a #### Rejection Summary (blocking issues with reviewer attribution) and a #### Remediation Prompt (self-contained, fenced ```text block the user can copy-paste into Claude to fix the plan and re-run the panel).
• Approve / Approve with revisions — unchanged (verdict line + rationale).

The remediation prompt is context-aware (interactive vs. background mode), handles edge cases (empty blocking issues, split decisions), and the re-run loop works cleanly via dated ## Panel Review headings that preserve history across runs.

Steps

1. Widen the outer fence in output-template.md from 3 to 5 backticks (lines 20 and 194). Why: CommonMark terminates a 3-backtick fence at the first 3-backtick line it encounters. Verify: Lines 20 and 194 use 5 backticks.
2. Add reject-only subsections to section 14 in output-template.md. Add #### Rejection Summary and #### Remediation Prompt. Why: Data contract that drives all downstream rendering. Verify: Subsections exist, gated by HTML comments.
3. Handle empty section 4 in the rejection summary template. Why: A panel can reject without formal blockers. Verify: Template addresses the empty-section-4 case explicitly.
4. Make the remediation prompt context-aware for background mode. Why: “Paste into Claude” is wrong in background mode. Verify: Template has both variants with a clear mode gate.
5. Update SKILL.md Step 6 — add a “Rejection remediation” paragraph. Why: The lead needs explicit cross-referencing instructions. Verify: Step 6 names sections 3, 4, 12, plan path, mode detection.
6. Use dated ## Panel Review headings in SKILL.md Step 7 with seconds precision. Why: Preserve review history; avoid collisions. Verify: Format is ## Panel Review (YYYY-MM-DD HH:MM:SS UTC).
7. Update html-spec.md — replace badge with decision banner, add remediation section. Why: HTML artifact must render decision status prominently. Verify: Banner replaces badge; no duplicate announcements.
8. Add Step 8 re-read instruction to SKILL.md. Why: Step 8 needs the plan content including the just-appended Panel Review. Verify: Step 8 instructions include re-reading the plan file.
9. Update the header comment in output-template.md. Why: Document the rejection flow and 5-backtick convention. Verify: Header mentions rejection flow.
10. Update the plugin README. Why: Documents user-visible output behavior. Verify: README mentions remediation prompt, decision banner, dated headings.
11. Bump version to 3.4.0 in CHANGELOG and marketplace.json. Why: New feature = MINOR bump. Verify: Both files updated.

Acceptance Criteria

Report output

• When the final decision is Reject, section 14 includes #### Rejection Summary and #### Remediation Prompt
• When the final decision is Approve or Approve with revisions, section 14 is unchanged
• The remediation prompt is a fenced ```text block containing: plan path, blocking issues, critical concerns, recommended changes, and re-run instructions
• The prompt is self-contained
• Interactive mode says “Copy and paste into Claude”; background mode says “Re-run the panel”
• Empty section 4 + Reject is handled with explanatory note
• No section renumbering (still 15 sections: 1-14, 15a, 15b)

Re-run loop

• Re-runs append a new dated ## Panel Review (YYYY-MM-DD HH:MM:SS UTC) section
• Reviewers in subsequent runs see all historical reviews
• 15a edits still apply on Reject (partial improvement) with a note that some may fail

HTML artifact

• Decision banner (<div role="status">) renders for all three outcomes
• No decision badge remains in <header>
• Reject banner includes remediation section with scrollable <pre>
• Clipboard JS has execCommand('copy') fallback; aria-live announces success/failure
• Copy button has aria-label (WCAG 4.1.2)
• Copy button hidden in print
• Historical reviews render as collapsed <details>, newest first
• Security & Escaping Contract covers remediation content
• CSS .remediation has color-mix() with fallback

Infrastructure

• Outer fence in output-template.md uses 5 backticks
• README documents new features
• Version bumped to 3.4.0

Verification

1. Read all modified files and confirm changes match acceptance criteria.
2. Trace the rejection path (interactive): output-template section 14 → Step 6 populates with “paste into Claude” variant → Step 7 applies 15a edits + appends dated Panel Review → Step 8 re-reads plan, renders HTML decision banner (red) + remediation.
3. Trace the rejection path (background): same but Step 6 uses “re-run the panel” variant.
4. Trace the approve path: no reject-only content; green decision banner; dated Panel Review still appended.
5. Trace the approve-with-revisions path: no reject-only content; amber decision banner; 15a edits apply normally.
6. Trace the re-run path: new dated heading appended without stripping; historical reviews as collapsed <details>.
7. Verify HTML skeleton: no badge in header; banner in main; role="status"; scrollable <pre>; clipboard JS; aria-live span; print styles.
8. Verify output-template.md: 5-backtick fence; both prompt variants; header comment.
9. Verify no section renumbering (still 15 sections).

Files to modify

Key design decisions

1. Reject-only remediation, not “approve with revisions”: Approve with revisions already has sections 12 + 15a. A lighter revisions prompt can follow later.
2. Inside section 14, not a new section: Avoids renumbering 15a/15b. Gated by HTML comments.
3. Reproduce, don’t summarize: Exact copies from sections 3/4/12 with reviewer role prefixes.
4. 5-backtick outer fence: CommonMark-spec-compliant nesting.
5. Banner replaces badge: Single <div role="status"> in <main>. No duplicate announcements.
6. Keep all reviews with dated headings: Seconds precision. No stripping. HTML renders each as collapsed <details>.
7. Apply 15a edits on Reject: Partial improvement is better than none.
8. Step 8 re-reads the plan file: Captures historical reviews for HTML generation.
9. execCommand('copy') fallback: Progressive enhancement for file:// origins.
10. aria-live pre-exists in DOM: WCAG 4.1.3 compliance.
11. Copy button aria-label: WCAG 4.1.2 compliance.
12. Scrollable <pre> with keyboard access: max-height: 300px, tabindex="0", role="region".
13. Mode-aware prompt variants in template: Single source of truth.
14. color-mix() with fallback: var(--surface) declared first.

Next Steps

• Add a lighter revisions prompt for Approve with revisions: extend the section 14 conditional structure with #### Revisions Summary and #### Revisions Prompt. Bump to 3.5.0.
• Add reviewer-prompt guard for ## Panel Review sections: instruct reviewers to treat historical reviews as context, not plan content.

Interview Summary

Interview conducted 2026-05-18. 14 key decisions confirmed across 3 rounds covering technical trade-offs, UI/UX flows, accessibility, and edge cases.

Key Decisions Confirmed

1. Keep historical reviews inline with dated headings
2. Both prompt variants in the template
3. Apply 15a edits on Reject
4. 5-backtick outer fence is safe
5. Always show a decision banner for all outcomes
6. All historical reviews in HTML as collapsed sections
7. Silent clipboard fail (visually); aria-live announces for assistive technology
8. role="status" on decision banner
9. Max-height with scroll on remediation <pre>
10. Manual trace verification
11. Include all three decision banners in this version

Open Risks

• Plan file growth with each re-run
• Decision banner scope increase beyond original ask
• Dated heading parsing adds logic to Step 8
• Scrollable <pre> a11y implementation complexity