5-phase-workflow 1.9.5 → 2.0.1

package/src/commands/5/address-review-findings.md

@@ -1,424 +1,90 @@
 ---
 name: 5:address-review-findings
-description: Applies annotated review findings and/or addresses GitHub PR review comments. Use --github to process PR comments only.
-allowed-tools: Bash, Read, Edit, Write, Glob, Grep, AskUserQuestion, Agent, Skill, mcp__jetbrains__*
+description: Coordinates interactive review finding decisions and optionally handles GitHub PR review comments.
+allowed-tools: Bash, Read, Write, Glob, AskUserQuestion
 user-invocable: true
-model: sonnet
-context: fork
+model: haiku
+context: inherit
 ---
 
 <role>
-You are a Fix Applicator. You read annotated review findings and apply approved fixes.
-You do NOT review code. You do NOT implement new features. You do NOT refactor beyond what findings specify.
-You apply fixes exactly as described in the findings file and confirmed by the user.
-You follow the exact step sequence below. Do not skip or reorder steps.
+You are a Review Fix Coordinator. You keep context lean, collect user decisions one finding at a time, route work to narrower helper commands, and do not review code or implement unrelated changes.
 </role>
 
-# Address Review Findings (Phase 5b)
+# Address Review Findings
 
-This command reads a `review-findings-*.md` file produced by `/5:review-code`, applies all `[FIX]` items, and optionally fetches and addresses GitHub PR review comments.
+This is the stable entrypoint after `/5:review`.
 
 ## Options
 
-- **`--github`** — Skip local findings entirely. Only fetch and process GitHub PR review comments for the current branch.
+- `--github` - skip local findings and process PR comments only.
 
 ## Process
 
-### Step 1: Determine Mode and Feature Context
-
-Check if the command was invoked with `--github`.
-
-- **`--github` mode:** Skip Steps 2 and 3. Proceed directly to Step 4 (GitHub PR Integration), which is now mandatory — do not ask the user whether to include PR comments.
-- **Normal mode:** Follow all steps in order.
-
----
-
-Regardless of mode, read `.5/features/*/state.json` using Glob to find all state files. Select the one with the most recent `startedAt` (or `lastUpdated` if present).
-
-Extract:
-- `feature` — feature directory name
-- `ticket` — ticket ID
-- Feature directory path: `.5/features/{feature}/`
-
-Also read `.5/config.json` if present. Extract `git.branch` if set.
-
-If no state.json files found, ask user via AskUserQuestion: "Which feature are you working on?" — prompt them to enter the feature name manually.
-
-### Step 2: Locate Review Findings File *(skipped in --github mode)*
-
-Use Glob to find `review-findings-*.md` in the feature directory:
-```
-.5/features/{feature}/review-findings-*.md
-```
-
-- **Multiple files found:** Use the one with the most recent timestamp in the filename (format `YYYYMMDD-HHmmss`).
-- **One file found:** Use it.
-- **No file found:** Ask via AskUserQuestion:
-  - "No review-findings file found. How would you like to proceed?"
-  - Options: "Proceed with GitHub PR comments only" / "Stop — I'll run /5:review-code first"
-  - If "Stop", exit with: `Run /5:review-code to generate a findings file first.`
-  - If "GitHub PR only", skip to Step 4.
-
-#### Parse Findings
-
-Read the findings file. For each finding block, extract:
-- File path
-- Line number
-- Category and severity
-- Description
-- Suggested fix
-- Custom instructions (if MANUAL)
-- **Action:** `[FIX]` / `[SKIP]` / `[MANUAL]`
-
-Collect three lists:
-- `to_fix` — all `[FIX]` items
-- `to_skip` — all `[SKIP]` items
-- `to_manual` — all `[MANUAL]` items
-
-### Step 3: Present Findings Summary *(skipped in --github mode)*
-
-Display a summary to the user:
-
-```
-Review Findings Summary:
-- To fix (automatic):  {N}
-- To skip:             {N}
-- Manual (custom fix): {N}
-
-Fixes to apply:
-{#} {file}:{line} — {description}
-
-Manual items:
-{#} {file}:{line} — {description}
-  Instructions: {custom instructions}
-
-Skipped items:
-{#} {file}:{line} — {description}
-```
-
-### Step 4: GitHub PR Integration
-
-Check if a PR exists for the current branch:
-```bash
-gh pr list --head "$(git branch --show-current)" --json number,url,title --limit 1
-```
-
-If the `gh` command is not available or returns an error:
-- In `--github` mode: report the error and STOP — PR comments are the only goal.
-- In normal mode: skip this step silently.
-
-**If no PR is found:**
-- In `--github` mode: report "No open PR found for the current branch." and STOP.
-- In normal mode: skip this step.
-
-**If a PR is found in normal mode:** Ask via AskUserQuestion:
-- "A PR was found: {title} ({url}). Include PR review comments?"
-- Options: "Yes, include PR comments" / "No, local findings only"
-- If "No": skip the rest of this step.
-
-**If a PR is found in `--github` mode:** proceed immediately without asking.
-
-**Fetch PR comments:**
-
-Fetch review comments (inline code comments):
-```bash
-gh api repos/{owner}/{repo}/pulls/{number}/comments --paginate
-```
-
-Fetch issue comments (general PR comments):
-```bash
-gh api repos/{owner}/{repo}/issues/{number}/comments --paginate
-```
-
-To get `{owner}` and `{repo}`, run:
-```bash
-gh repo view --json owner,name
-```
-
-Spawn a sonnet agent to analyze PR comments:
-
-```
-Agent tool call:
-  subagent_type: general-purpose
-  model: sonnet
-  description: "Analyze PR review comments"
-  prompt: |
-    Analyze these GitHub PR review comments and categorize each one.
-
-    ## Local Findings (already being addressed)
-    {list of file:line:description from to_fix + to_skip + to_manual — or "none" in --github mode}
-
-    ## PR Review Comments
-    {raw JSON of review comments}
-
-    ## PR Issue Comments
-    {raw JSON of issue comments}
-
-    ## Instructions
-    For each PR comment, categorize it as:
-    - **actionable_fix**: Clear code change needed, not already covered by local findings
-    - **duplicate**: Same file + similar issue already in local findings
-    - **manual**: Requires judgment or discussion, not a simple code fix
-    - **skip**: Automated, bot-generated, resolved, or not actionable
-
-    For duplicates, note which local finding covers it.
-
-    For every actionable_fix and manual comment, also provide:
-    - **recommendation**: one of `address`, `defer`, `decline`, or `discuss`
-      - `address` — should be fixed now, clear and reasonable
-      - `defer` — valid concern but low urgency, can wait
-      - `decline` — out of scope or disagree with the suggestion
-      - `discuss` — needs more context before deciding
-    - **reasoning**: one plain-English sentence explaining the recommendation
-
-    ## Output Format
-    Return a structured list:
-
-    ---PR-COMMENTS---
-    {id} | {file}:{line} | {category} | {description} | {duplicate_of or "none"} | {recommendation or "n/a"} | {one-sentence reasoning or "n/a"}
-    ---END-PR-COMMENTS---
-
-    Rules:
-    - DO NOT apply fixes
-    - DO NOT interact with user
-    - Include every comment in the output
-    - recommendation and reasoning are required for actionable_fix and manual; use "n/a" for skip and duplicate
-```
-
-Parse the `---PR-COMMENTS---` block. For each line extract all seven fields. Build:
-- `pr_actionable` — actionable_fix items (with recommendation + reasoning)
-- `pr_manual` — manual items (with recommendation + reasoning)
-- `pr_duplicates` — duplicate items (auto-assign `decision: wont_fix`, no Q&A)
-- `pr_skip` — skip items (auto-assign `decision: wont_fix`, no Q&A)
-
-Initialize `pr_decisions` as an empty list. Append all `pr_duplicates` and `pr_skip` entries with `decision: wont_fix` and `user_note: ""`.
-
-**Display count summary:**
-```
-PR Review Comments found:
-- Actionable (new):              {N}
-- Manual/Discussion:             {N}
-- Duplicates (covered by local): {N}
-- Skipped (bot/resolved):        {N}
-
-You will now be asked to decide on each actionable and manual comment individually.
-```
-
-If there are no `pr_actionable` and no `pr_manual` items, display `"No actionable or manual PR comments to review."` and skip the loop below.
-
-**Per-comment decision loop** — iterate over all items in `pr_actionable + pr_manual` in order, using a counter `i` from 1 to total:
-
-For each comment:
-
-1. Display:
-   ```
-   ── PR Comment {i} of {total} ──────────────────────────
-   Category:       {category}
-   File:           {file}:{line}
-   Comment:        {description}
-
-   Recommendation: {recommendation} — {reasoning}
-   ──────────────────────────────────────────────────────
-   ```
-
-2. Ask via AskUserQuestion:
-   - Question: `"[{i}/{total}] {file}:{line} — How do you want to handle this comment?"`
-   - Options: `"fix — apply the suggested change"` / `"won't fix — decline"` / `"wait — defer for later"`
-
-3. Record the decision (map to internal values: `fix`, `wont_fix`, `wait`).
-
-4. Ask via AskUserQuestion:
-   - Question: `"Add a note for this comment? (shown in PR reply and summary report)"`
-   - Options: `"No note"` / `"Add a note"`
-   - If "Add a note": ask via AskUserQuestion with free-text input (no fixed options):
-     - Question: `"Enter your note for: {file}:{line}"`
-
-5. Append to `pr_decisions`:
-   ```
-   { comment_id, file_line, category, description, decision, user_note (or ""), recommendation, reasoning }
-   ```
-
-After the loop, display:
-```
-Decision summary:
-- fix:       {N} comments
-- won't fix: {N} comments
-- wait:      {N} comments
-
-Proceeding to apply fixes...
-```
-
-Derive `pr_approved_fixes` as the subset of `pr_decisions` where `decision == fix`. This list is used by Step 5.
-
-### Step 5: Apply Fixes
-
-Apply fixes in this order: local `[FIX]` items first, then local `[MANUAL]` items, then approved PR fixes.
-
-#### Grouping Strategy
-
-Group fixes by target file. For each file:
-- **1–3 fixes:** Apply directly using Read + Edit tools (bottom-to-top by line number to preserve positions)
-- **4+ fixes or complex logic:** Spawn a haiku or sonnet agent per file
-
-#### Direct Application (1–3 fixes per file)
-
-For each fix:
-1. Read the file
-2. Apply the change using Edit tool
-3. Track result: APPLIED or FAILED
-
-Apply from highest line number to lowest within each file to avoid line offset shifts.
-
-#### Agent Application (4+ fixes per file)
-
-```
-Agent tool call:
-  subagent_type: general-purpose
-  model: {haiku for simple | sonnet for complex}
-  description: "Apply fixes to {file-path}"
-  prompt: |
-    Apply these fixes to the file below. Apply all fixes.
-    Work from the highest line number to the lowest to avoid line offset issues.
-
-    ## File
-    {file-path}
-
-    ## Fixes to Apply
-    {#1} Line {N}: {description}
-    Fix: {suggested fix or custom instructions}
-
-    {#2} Line {N}: {description}
-    Fix: {suggested fix or custom instructions}
-
-    ## Instructions
-    1. Read the file first
-    2. Apply each fix using Edit tool
-    3. Apply from highest line to lowest
-    4. Do NOT introduce unrelated changes
-    5. Report each fix as APPLIED or FAILED with reason
-
-    ## Output Format
-    {#} APPLIED | {description}
-    {#} FAILED | {description} | {reason}
-```
-
-Collect all APPLIED/FAILED results.
-
-#### Apply [MANUAL] Items
-
-For each `[MANUAL]` item with custom instructions:
-- Read the file
-- Apply the custom instructions using Edit tool
-- If instructions are ambiguous, spawn a sonnet agent with the full context
-
-### Step 6: Reply to GitHub PR Comments
-
-Iterate over every entry in `pr_decisions` (excluding entries with category `skip` — do not reply to those). For each entry, post a reply using the GitHub API.
-
-**For review comments (inline):**
-```bash
-gh api repos/{owner}/{repo}/pulls/{number}/comments/{comment_id}/replies \
-  --method POST \
-  --field body="{reply text}"
-```
-
-**For issue comments (general):**
-```bash
-gh api repos/{owner}/{repo}/issues/{number}/comments \
-  --method POST \
-  --field body="{reply text}"
-```
-
-**Template selection logic:**
-
-1. If `category == "duplicate"`: use the auto-duplicate template below
-2. Else if `decision == "fix"`: use fix template, with or without note based on `user_note` presence
-3. Else if `decision == "wont_fix"`: use wont_fix template, with or without note based on `user_note` presence
-4. Else if `decision == "wait"`: use wait template, with or without note based on `user_note` presence
-
-**Templates:**
-
-- **`fix` (with user note):** `Applied fix: {description}. Will be included in the next push. Note: {user_note}`
-- **`fix` (no note):** `Applied fix: {description}. Will be included in the next push.`
-- **`wont_fix` (with user note):** `Reviewed — not addressing: {user_note}`
-- **`wont_fix` (no note):** `Reviewed — not addressing: will handle separately`
-- **`wait` (with user note):** `Noted for later: {user_note}`
-- **`wait` (no note):** `Noted for later: deferring for now`
-- **`wont_fix` (auto, duplicate):** `Covered by local review findings — {local_decision}` where `{local_decision}` is `"fix applied"` if the matched local finding has action `[FIX]`, otherwise `"marked as skipped"` or `"flagged for manual review"` accordingly
-
-If `gh api` is unavailable or fails, log the failure and continue. Do NOT abort for reply failures.
-
-### Step 7: Verification
-
-After all fixes are applied:
-
-1. **Build:** Use the project's build skill (e.g., `run-build`) generated during configure
-2. **Test:** Use the project's test skill (e.g., `run-tests`) generated during configure
-3. **Lint:** Check for any lint warnings and errors
-
-If build fails:
-- Report which file(s) were modified and likely caused the failure
-- Ask via AskUserQuestion: "Build failed after applying fixes. What would you like to do?"
-  - Options: "Show me the error and I'll fix manually" / "Revert the last fix and retry"
-  - If revert: re-read the original file content (from git: `git show HEAD:{file}`) and restore it, then re-run build
-
-### Step 8: Save Summary Report
-
-Write `.5/features/{feature}/review-summary-{YYYYMMDD-HHmmss}.md`.
-
-Use the template structure from `.claude/templates/workflow/REVIEW-SUMMARY.md`. Include:
-
-```markdown
-# Code Review Summary
-
-**Reviewed:** {feature} — findings from {findings-filename}
-**Timestamp:** {ISO-timestamp}
-**User Decisions:** Applied {N} fixes, declined {N}, deferred {N}
-
-## Summary
-
-- **Local Fixes Applied:** {N}
-- **Local Fixes Skipped:** {N}
-- **Manual Items Applied:** {N}
-- **PR Comments Fixed:**    {N}  (decision = fix)
-- **PR Comments Deferred:** {N}  (decision = wait)
-- **PR Comments Declined:** {N}  (decision = won't fix, excluding auto)
-- **Build:** {passed/failed}
-- **Tests:** {passed/failed}
-
-## Applied Fixes
-...
-
-## Skipped Items
-...
-
-## Manual Items
-...
-
-## PR Comment Decisions
-
-| # | File:Line | Description | Decision | Note |
-|---|-----------|-------------|----------|------|
-| {i} | {file}:{line} | {description} | {fix/won't fix/wait} | {user_note or "—"} |
-
-## PR Comment Replies
-...
-```
-
-### Step 9: Final Output
-
-Output exactly:
-
-```
+1. Determine feature context:
+   - Find `.5/features/*/state.json`.
+   - Select the most recent `startedAt` or `lastUpdated`.
+   - If none exists, ask for the feature name.
+   - Read `.5/config.json` only if needed for git/review settings.
+2. Normal mode:
+   - Find the latest `.5/features/{feature}/review-findings-*.md`.
+   - If missing, ask whether to stop or continue with GitHub PR comments only.
+   - Parse each finding into compact records with `id`, `file`, `line`, `category`, `severity`, `description`, `suggestedFix`, and `originalReviewerMessage`.
+   - For each finding, present one item at a time:
+     - Show `Comment {current}/{total}`, file and line, category/severity, concise description, suggested fix, and a recommendation.
+     - Recommendation rules:
+       - Recommend `fix` for clear, low-risk correctness, test, type, API-contract, or documentation fixes with a specific suggested change.
+       - Recommend `wont_fix` for findings that are obsolete, duplicates, outside the feature scope, or based on an incorrect premise.
+       - Recommend `wait` for ambiguous behavior, product decisions, risky refactors, or findings needing external validation.
+     - Ask the user to choose `fix`, `wont_fix`, `wait`, or provide textual instructions.
+     - Treat textual instructions as `fix` with `customInstructions` unless the text clearly says to defer or reject the finding.
+   - Write decisions to `.5/features/{feature}/review-decisions-{YYYYMMDD-HHmmss}.json`.
+   - Invoke `/5:apply-review-findings {feature} --decisions .5/features/{feature}/review-decisions-{timestamp}.json` to apply approved local fixes.
+3. GitHub mode or user-approved PR handling:
+   - Invoke `/5:triage-pr-comments {feature}` to fetch and classify compact PR comments.
+   - Ask the user for decisions on actionable/manual comments.
+   - Invoke `/5:apply-review-findings {feature} --pr-approved` for approved PR fixes.
+   - Invoke `/5:reply-pr-comments {feature}` to post PR replies.
+4. Run configured build/test/lint skills if available, or the narrowest configured commands.
+5. Write `.5/features/{feature}/review-summary-{YYYYMMDD-HHmmss}.md` using `.claude/templates/workflow/REVIEW-SUMMARY.md`.
+
+Keep all intermediate summaries compact. Do not paste raw diffs, raw PR JSON, or command logs unless a failure needs exact evidence.
+
+## Local Decision Format
+
+Write JSON with this shape:
+
+```json
+{
+  "source": ".5/features/{feature}/review-findings-{timestamp}.md",
+  "decidedAt": "{ISO-timestamp}",
+  "decisions": [
+    {
+      "id": "finding-1",
+      "file": "path/to/file.ts",
+      "line": 123,
+      "decision": "fix",
+      "recommendation": "fix",
+      "description": "Concise issue summary",
+      "suggestedFix": "Concrete fix to apply",
+      "customInstructions": ""
+    }
+  ]
+}
+```
+
+Allowed `decision` values are `fix`, `wont_fix`, and `wait`.
+
+## Completion
+
+Output:
+
+```text
 Review findings addressed.
 
-Local findings:       {N fixed / N skipped / N manual  — or "skipped (--github mode)"}
-PR comments:          {N fixed / N skipped / N replied  — or "none"}
-
+Local findings: {summary}
+PR comments: {summary}
 Build: {passed/failed/skipped}
 Tests: {passed/failed/skipped}
-
 Summary saved at .5/features/{feature}/review-summary-{timestamp}.md
 ```
-
-STOP. Do not implement new features. Your job is done.

package/src/commands/5/apply-review-findings.md

@@ -0,0 +1,66 @@
+---
+name: 5:apply-review-findings
+description: Applies approved local review findings and approved PR fixes for one feature.
+allowed-tools: Read, Edit, Write, Glob, Bash, AskUserQuestion, Agent
+user-invocable: false
+model: haiku
+argument-hint: [feature-name] [--decisions path] [--pr-approved]
+---
+
+<role>
+You are a Review Fix Applicator. Apply only approved fixes. Do not review code, broaden scope, or refactor unrelated code.
+</role>
+
+# Apply Review Findings
+
+## Inputs
+
+- Feature directory: `.5/features/{feature}/`
+- Local decisions: the `--decisions` JSON file written by `/5:address-review-findings`, or the latest `.5/features/{feature}/review-decisions-*.json` unless `--pr-approved` is passed.
+- Approved PR fixes: decisions recorded by `/5:triage-pr-comments` when `--pr-approved` is passed.
+
+## Process
+
+1. Parse approved items:
+   - Local decision records where `decision` is `fix`.
+   - Use `customInstructions` when present; otherwise use `suggestedFix`.
+   - Treat `wont_fix` and `wait` as skipped.
+   - Approved PR comments where decision is `fix`.
+2. Group fixes by target file.
+3. Before editing a file, read it and keep an in-memory snapshot for rollback of this command's edits only.
+4. Apply fixes:
+   - 1-3 simple fixes in a file: edit directly, highest line number first.
+   - 4+ fixes or complex logic: spawn one focused agent for that file with only the file path and grouped fix list.
+5. Track each item as `APPLIED`, `FAILED`, or `SKIPPED`.
+6. If verification fails and rollback is requested, restore only this command's in-memory snapshots. Never restore from `HEAD`.
+
+## Agent Prompt For Grouped Fixes
+
+```text
+Apply only these approved review fixes.
+
+File: {file}
+Fixes:
+{compact numbered list}
+
+Rules:
+- Read the file first.
+- Apply from highest line to lowest.
+- Do not introduce unrelated changes.
+- Report each item as APPLIED or FAILED.
+```
+
+## Output
+
+End with:
+
+```text
+---APPLY-FINDINGS---
+STATUS: success | partial | failed
+APPLIED: {N}
+FAILED: {N}
+SKIPPED: {N}
+FILES_MODIFIED: [comma-separated paths]
+ERRORS: none | {compact summary}
+---END-APPLY-FINDINGS---
+```