fix

Fix Executor

You are executing fixes from a specified document. Your role is strictly mechanical: read the instructions, do exactly what they say, validate, and commit. Do not question, interpret, or modify anything.

Invocation

The user will invoke this as /fix <document-path>. The document can be either a .toml plan (preferred) or a legacy .md plan. Read that document, then work through it task by task.

Task Sidecar Script

This plugin includes a shared scripts/task-sidecar.sh (at the plugin root) for enumerating issues and preparing verification sidecars. It reads from the compiled manifest.json — the single source of truth for task IDs, descriptions, and acceptance commands. Code changes are applied exclusively by compiled scripts.

# List all issue/fix IDs from the compiled manifest
bash <plugin-root>/scripts/task-sidecar.sh list <fix-doc-dir>/compiled/manifest.json

# Create sidecar file for hook-automated verification
bash <plugin-root>/scripts/task-sidecar.sh prepare <fix-doc-dir>/compiled/manifest.json <issue-id>

Resolve <plugin-root> before running any sidecar command. Run the following command once and record the printed path — use it as the literal value everywhere <plugin-root> appears in this section:

python3 -c "
import json; from pathlib import Path
p = Path.home() / '.claude/plugins/installed_plugins.json'
data = json.loads(p.read_text())
for key in ['fortran-dev-pipeline@my-claude-marketplace', 'fortran-dev-pipeline@local']:
    if key in data['plugins']:
        print(data['plugins'][key][0]['installPath']); break
"

If the command prints nothing, the plugin is not registered — stop immediately and report: "Plugin root could not be resolved from installed_plugins.json." Do not guess or construct the path manually.

CRITICAL: The orchestrator must NOT run the compiled scripts or prepare commands itself. These are executed by the delegated implementation-executor subagent. The orchestrator only constructs the prompt template and launches the agent.

Agent Prompt Template

When launching an implementation-executor agent for a fix, you must use subagent_type: "fortran-dev-pipeline:implementation-executor" in the Agent tool call — never use the default general-purpose agent. Using the wrong agent type means the coding standards and quality gates defined in the implementation-executor agent definition will not be applied.

Use this template as the prompt body:

You are executing {ISSUE_ID} from the fix document at {DOC_PATH}.

Step 1: Write the verification sidecar for the post-task hook by running:
  bash {SCRIPT_PATH} prepare "{MANIFEST_PATH}" {ISSUE_ID}
This writes acceptance criteria so the SubagentStop hook can verify your work
automatically. Do this BEFORE making any code changes.

Step 2: Run the compiled script:
  bash {COMPILED_SCRIPT_PATH}

  IMPORTANT: A PostToolUse hook will automatically stop you after this
  command completes. You do NOT need to do anything else — no validation,
  no LSP checks, no summary. The SubagentStop hook handles verification,
  checkpointing, and committing. Just run the script and stop.

  If the Bash tool reports a non-zero exit code, that information is
  captured automatically. Do NOT attempt manual implementation — compiled
  scripts are the only execution path.

Replace:

• {ISSUE_ID} — the issue/fix identifier (e.g., Issue-1, Fix-2)
• {DOC_PATH} — absolute path to the fix document
• {SCRIPT_PATH} — absolute path to the plugin's scripts/task-sidecar.sh
• {MANIFEST_PATH} — absolute path to <fix-doc-dir>/compiled/manifest.json
• {COMPILED_SCRIPT_PATH} — absolute path to the compiled .sh script for this task, constructed as <fix-doc-dir>/compiled/<ISSUE-ID>.sh. The compiled/ directory is a sibling of the fix document, generated by /compile-plan.

Critical: The Agent tool call must always include subagent_type: "fortran-dev-pipeline:implementation-executor" and name: "{ISSUE_ID}". The name field makes the agent addressable via SendMessage and is used by the SubagentStop hook to locate the correct sidecar. Example skeleton:

Agent({
  subagent_type: "fortran-dev-pipeline:implementation-executor",
  name: "{ISSUE_ID}",
  description: "Execute Issue-1: fix missing INTENT declaration",
  prompt: "<filled template above>"
})

Pre-flight: Ensure Compiled Scripts Exist

Before launching any task agents, the orchestrator must ensure compiled scripts are available:

1. Look for <fix-doc-dir>/compiled/manifest.json (sibling to the fix document).
2. If the compiled/ directory or manifest.json does not exist, run the /compile-plan <fix-doc-path> skill on the fix document first to generate them. This always succeeds with full task coverage.
3. Once manifest.json exists, read it. Every task will have a compiled script at compiled/<ISSUE-ID>.sh.

This ensures compiled scripts are always available before any task agent is launched.

Checkpoint / Resume

Before doing anything else, check for a checkpoint file:

fix_reports/.checkpoint_<doc-slug>.json

where <doc-slug> is the fix document filename without extension.

If the checkpoint exists, read it:

{
  "document": "<doc-path>",
  "base_commit": "a1b2c3d4e5f6789...",
  "completed": ["Issue-1", "Issue-2"],
  "failed": [],
  "blocked": []
}

Inform the user: "Resuming from checkpoint — Issue-1, Issue-2 already completed. Starting from Issue-3." Then skip all tasks in completed, failed, and blocked.

If no checkpoint exists, start fresh.

During execution: after each task passes validation, immediately update the checkpoint. On full completion (report written, commit created): delete the checkpoint file.

Execution Workflow

1. Parse the fix document:

   • Resolve <plugin-root> using the command in the "Task Sidecar Script" section above, then run bash <plugin-root>/scripts/task-sidecar.sh list <fix-doc-dir>/compiled/manifest.json to enumerate all issue/fix IDs
   • Read the ## Order of Operations or ## Prerequisites section in the fix document (if present) to determine the actual execution sequence. Task IDs may not be numbered in execution order. If no ordering section exists, fall back to ascending ID order.

2. Compile the fix document (produces deterministic scripts for each task):

   • Look for compiled/manifest.json in the same directory as the fix document
   • If it does NOT exist, compile the document by invoking /compile-plan <fix-doc-path>, then read the resulting manifest
   • Read compiled/manifest.json. Every task has a pre-compiled shell script at compiled/<ISSUE-ID>.sh that applies changes deterministically via sd -F

3. Execute tasks sequentially — one at a time:

   • CRITICAL: For EVERY task, you MUST launch the implementation-executor agent (via the Agent tool with subagent_type: "fortran-dev-pipeline:implementation-executor"). Do NOT implement fixes yourself inline.
   • CRITICAL: Honour the fix document's order of operations. If the document has an "Order of Operations" or "Prerequisites" section, treat that order as mandatory. Do NOT start Fix N+1 until Fix N has passed validation. A prerequisite fix that fails validation is a hard blocker — do not proceed past it.
   • CRITICAL: Multi-part fixes are atomic. If a fix has sub-changes labelled (a), (b), (c) … or "Change 1 / Change 2 / …", delegate ALL sub-changes to a single implementation-executor agent call. Never split sub-changes across separate agent calls. An implementation-executor that applies only some sub-changes and exits leaves the file in a broken intermediate state.
   • Complete each task fully before moving to the next:
     1. Launch implementation-executor agent using the Agent Prompt Template above. Set subagent_type: "fortran-dev-pipeline:implementation-executor", pass the script path, document path, issue ID, and compiled script path (<fix-doc-dir>/compiled/<ISSUE-ID>.sh). Do NOT copy fix content into the prompt; the agent runs the compiled script directly.
     2. Wait for the agent to complete. A SubagentStop hook automatically runs acceptance commands, updates the checkpoint, appends to the execution report, and commits. The hook returns a reason field with ground-truth verification results — trust the hook's output over the subagent's claim of success/failure.
     3. Read the hook's verification results from the agent completion output. The hook reports PASSED/FAILED per acceptance command, checkpoint status, and commit hash.
     4. If the hook reports failure:
        • Diagnose before retrying: Before launching a retry agent, run these diagnostic checks on the failing task:
          1. Read the TOML fix document and extract the before content for each [[changes]] entry in the failing task
          2. For each before block, grep the target file for a distinctive substring (first non-whitespace line, ~40 chars)
          3. Classify the failure:
             • Content shifted: substring found but full before block doesn't match → prior tasks shifted the content. Note the actual surrounding context in the retry prompt so the agent can adapt.
             • Already applied: the after content is already present in the file → the change was applied but a later step failed. Skip this change entry in the retry.
             • Content missing: substring not found and after not present → fundamental mismatch. Flag for manual review.
          4. Include the diagnostic classification in the retry agent's prompt as additional context
        • Launch a new implementation-executor agent (same subagent_type) to retry, with diagnostic context appended to the prompt (up to 3 attempts total)
        • If still fails after 3 attempts: mark as failed, stop execution entirely for dependent tasks; mark dependents as "Blocked" in the report
     5. If the hook reports success: proceed to next task
   • Tasks declared independent (no ordering dependency) MAY be launched in parallel — the sidecar mechanism uses per-task filenames (current_task_{ISSUE_ID}.json) so concurrent subagents do not conflict. Tasks with declared ordering dependencies must remain sequential.
   • Track: task status, attempt count, files modified, validation output

4. Run workspace-wide lint sweep:

   • Run a full project build with all warnings enabled: make FFLAGS="-Wall -Wextra" 2>&1 or fpm build --flag "-Wall -Wextra" 2>&1
   • If the compiler reports warnings or errors in files touched by ANY task in this round, these are blocking — create inline fix commits before proceeding to finalization
   • If the compiler reports warnings only in files NOT touched this round, note them in the execution report but do not block
   • Run the project test suite if applicable to ensure nothing broke

5. Finalize the execution report:

   • The hook has already appended per-task results to fix_reports/fix_<document-name>_<timestamp>.md
   • Append the Summary section (total tasks, passed, failed, overall status) and Final Validation results
   • Update the Status field in the report header

6. Commit finalization:

   • The hook already committed per-task; create a final commit for the summary/final validation if needed
   • Do NOT delete the checkpoint file yet — step 7 needs base_commit from it

7. Write branch status snapshot:

   After committing, determine the current branch name (git branch --show-current), then write (or overwrite) notes/pr-reviews/{branch}/status.md using the template below. This file is consumed by review-pr at startup so the next reviewer doesn't need to reconstruct codebase state from raw diffs and commit history.

   # Branch Status: `{branch}` — {YYYY-MM-DD}
   
   ## Last Fix Round
   
   - **Fix document**: `{path-to-fix-document}`
   - **Applied**: {YYYY-MM-DD HH:MM}
   - **Tasks**: {N} total — {P} passed, {F} failed, {B} blocked
   
   ## Files Modified This Round
   
   - `{file}` — {one-line description of what was fixed}
   - ...
   
   ## Outstanding Issues
   
   {List any failed or blocked tasks with their one-line description, or "None — all tasks passed."}
   
   ## Build Status
   
   - **gfortran -c -Wall**: {Passed / Failed — one-line error summary}
   - **Tests**: {Passed / N failed / Skipped}
   
   ## Branch Summary
   
   {1–2 sentences on the overall state of the branch: what has been fixed across all rounds, what (if anything) remains before merge.}
   
   ## Diff Snapshot
   
   {For each file modified this round, read `base_commit` from the checkpoint
   file (`fix_reports/.checkpoint_<doc-slug>.json`) and diff the entire round.
   Run: git diff <base_commit> HEAD -- {file}
   Embed the output verbatim in a fenced block labelled with the file path.}
   
   ### `{file}`
   
   ```diff
   {output of: git diff <base_commit> HEAD -- {file}}
   ```
   

   {repeat for each modified file}

   
   Then stage and commit the snapshot:
   
   ```bash
   git add notes/pr-reviews/{branch}/status.md
   git commit -m "fix({branch}): update branch status snapshot"
   

   After committing the snapshot, delete the checkpoint file (fix_reports/.checkpoint_<doc-slug>.json).

   If notes/pr-reviews/{branch}/ does not exist yet, create the directory before writing.

Validation Logic

Tell the implementation-executor every time.

For each task:

• First: Check LSP diagnostics immediately after code changes to catch syntax/type errors early
• If the fix document specifies acceptance criteria, run those checks
• For Fortran code changes: Check LSP diagnostics first, then compile with gfortran -c -Wall <file>.f90 or the project build command
• For test-related fixes: run the project test suite to verify tests pass
• For symbol renames: Use LSP rename instead of manual edits, verify with LSP references
• Check exit codes (0 = success, non-zero = failure)
• Capture full stdout and stderr for the report

LSP validation workflow for fixes:

1. After each fix: immediately check LSP diagnostics for the modified file
2. If diagnostics show errors: fix them before proceeding to acceptance commands
3. Use LSP hover to verify subroutine signatures match expectations after the fix
4. Use LSP references to ensure fixes didn't break call sites

Execution Report Format

# Fix Execution Report: <Document Name>

**Document**: <path-to-fix-document>
**Started**: <ISO 8601 timestamp>
**Completed**: <ISO 8601 timestamp>
**Status**: <All Passed | Partial Success | Failed>

## Task Results

### Issue-1: <description>

- **Status**: ✓ Passed
- **Attempts**: 1
- **Files modified**: <list>
- **Validation output**:

<stdout/stderr from validation>

### Issue-2: <description>
- **Status**: ✗ Failed
- **Attempts**: 3
- **Files modified**: <list>
- **Validation output**:

<stdout/stderr from last attempt>

- **Error**: <error message>

## Final Validation

**Lint sweep (gfortran -Wall -Wextra)**: <Passed | Failed | Skipped>
**Tests**: <Passed | Failed | Skipped>

## Summary

- Total tasks: X
- Passed: Y
- Failed: Z
- Overall status: <All Passed | Partial Success | Failed>

Commit Message Format

All tasks pass:

fix: <brief summary from document>

✓ Issue-1: <description>
✓ Issue-2: <description>
✓ Issue-3: <description>

All fixes applied successfully. See fix_reports/fix_<name>_<timestamp>.md

Some tasks fail:

fix: partial fixes for <brief summary>

✓ Issue-1: <description>
✓ Issue-2: <description>
✗ Issue-3: <description> (failed after 3 attempts - <brief error>)

See fix_reports/fix_<name>_<timestamp>.md for details.

Rules

• Always use the task sidecar script for sidecar preparation — run scripts/task-sidecar.sh prepare before each task to write the verification sidecar. The compiled script handles all code changes.
• Use the task sidecar script for enumeration — at the start, run scripts/task-sidecar.sh list to discover all issue/fix IDs from the manifest rather than parsing the document yourself.
• Compiled scripts are the only execution path — never attempt manual code changes based on fix descriptions. If the compiled script fails, report the error and retry; do not fall back to LLM-interpreted edits.
• Use LSP tools first — before fixing code, use LSP to understand structure; after fixing, check LSP diagnostics before compiling
• Do not ask questions — if something is ambiguous, make the most conservative interpretation and proceed
• Do not make decisions outside what the document specifies — no refactoring, no improvements, no "while I'm here" changes
• Complete one task fully before moving to the next — including all retry attempts
• Respect declared order of operations — if the fix document specifies an order, that order is mandatory. Validation must pass for each fix before the next begins. A failed prerequisite fix is a hard blocker; skip all fixes that depend on it and mark them "Blocked".
• Multi-part fixes are a single atomic unit — if a fix contains labelled sub-changes (a/b/c… or Change 1/2/3…), all sub-changes go to one implementation-executor agent call. Never split them. Partial application leaves the codebase in a broken intermediate state.
• A failed prerequisite blocks dependents — if Fix N fails after 3 attempts and Fix M depends on Fix N, mark Fix M as "Blocked (Fix N failed)" in the report without attempting it.
• If a task is already done (the fix is already in place): note it briefly in the report, mark as passed, continue
• Use conservative interpretation — when in doubt, do the minimal thing that satisfies the task description
• Ignore line numbers as addresses — if the fix document references file.f90:42, treat 42 as a hint only. Re-locate the target by searching for the surrounding code context (unique string, subroutine name, or LSP symbol) before each edit.
• Stage untracked files — if a task creates new files, stage them for commit
• Use modern tools — fd instead of find, rg instead of grep
• Prefer LSP for refactoring — use LSP rename for symbol changes, not manual find-replace

Error Handling

• Fix document doesn't exist: Error immediately with clear message, do not proceed
• Task validation fails: Log failure, retry up to 3 times, then mark as failed and continue
• Build or tests fail: Note in report, include in commit message, but still commit
• Git commit fails: Report error to user, do not retry