| name | run-fix |
| description | Extends an existing implementation project with a scoped fix. Use when a human identifies a gap or missed requirement post-implementation. Never trigger automatically. |
Run Fix Skill
Extend an existing implementation project with a scoped fix plan. This skill is always triggered
by a human identifying a specific gap — never by an agent acting on its own initiative.
The fix lives in the same project directory as the original implementation. It adds new artifacts
without modifying the original design plan, implementation plan, or journal.
When to use
Use this skill when, after a run-implementation project is complete, a human identifies a
missed requirement or incorrect behaviour that needs a targeted fix — through code review, UAT,
or manual testing feedback.
This is a standalone skill triggered directly by humans. It always operates within an existing
project directory created by run-implementation.
Do not use when:
- The gap is discovered during a PR review → use
review-pr instead
- The bug is unrelated to an existing implementation project → use
run-bug-fix or
run-hotfix instead
- The change is a new feature rather than a fix → start a new
run-implementation project
- No agent triggered this — this skill must never be triggered automatically
Prerequisites
Your prompt must include:
- Path to the existing project directory (
.artifacts/{project}/)
- A clear description of the gap or missed requirement to fix
If either is missing, ask before proceeding. Do not guess.
When to use this skill
Use this skill when, after implementation is complete, a human identifies something that was
missed — through code review, UAT, or operational feedback. Examples:
- An AC was not met
- A key design constraint was not implemented correctly
- A behaviour is wrong in a way that requires targeted changes
Do NOT use this skill to:
- Add new features (start a new project with
run-implementation instead)
- Make broad architectural changes (those require a new design plan)
- Fix things proactively — only when a human explicitly requests it
Artifacts
All artifacts are written to the existing project directory alongside the original artifacts.
| Artifact | Description |
|---|
implementation-plan--fix-{N}.md | Scoped fix plan (N = zero-padded 2 digits: 01, 02, ...) |
implementation-review--fix-{N}--{M}.md | Fix plan review (N = fix number, M = zero-padded iteration: 01, 02, ...) |
implementation-journal--fix-{N}.md | Execution journal for the fix |
execution-review--fix-{N}--whole-plan--{M}.md | Execution review (N = fix number, M = zero-padded iteration: 01, 02, ...) |
Use the next available N by checking what fix artifacts already exist in the project directory.
Git workflow
This skill manages its own git commits throughout the workflow. The --agents branch should
already exist from the original run-implementation run. If it does not, create it from the
current branch following the same rules in run-implementation.
Extract the Jira ID from the parent branch name using the same rules as run-implementation.
Commits after each approved stage
After the human approves each stage, commit and push:
git add -A
git commit -m "<message>"
git push origin {branch}--agents
Stage-specific commit types:
- After fix plan approved:
docs(<jira-id>): add fix-{N} plan for {project-name}
- After fix execution approved:
fix(<jira-id>): apply fix-{N} for {project-name}
Final squash onto parent branch
After the human approves the fix execution and the CHANGELOG is updated, squash all new
--agents commits (those not already on the parent branch) onto the parent branch:
- Propose a squash commit message to the human. Wait for explicit approval.
- Once approved:
git switch {parent-branch}
git merge --squash {parent-branch}--agents
git commit -m "<approved message>"
- Do NOT delete the
--agents branch.
- Do NOT push the parent branch — that is the human's decision.
Process
1. Plan
Read the existing implementation-plan.md and design-plan.md to understand the project context.
Dispatch an engineer-planner subagent to create implementation-plan--fix-{N}.md. The prompt
must include:
- The specific gap or missed requirement
- Path to the existing project directory
- Instruction to scope the plan narrowly — only what is needed to address the gap, nothing more
- Instruction to read
.agents/artifacts/implementation-plan/description.md for section definitions,
render .agents/artifacts/implementation-plan/template.md.j2 to produce the initial file, and replace
all dummy content with real content. The rendered file must contain no placeholder text when submitted.
Then dispatch an architect-reviewer subagent with the review-implementation-plan skill, the
fix plan path, and iteration 01.
Address all findings from the review:
- Apply trivial findings directly without discussion.
- Apply significant and critical findings using judgment. If a finding is genuinely ambiguous —
where the correct resolution depends on information only the human has — flag it inline and
note what you need. Do not stop the workflow for findings you can resolve yourself.
- Record the outcome in each finding's
##### Outcome subsection.
- Re-dispatch an
architect-reviewer at M+1 if changes were substantial. Repeat until the
agent reviewer approves.
STOP — end your turn here.
The fix plan is ready for human review. Present it to the human. Do not summarize the agent
findings — the human will read the plan directly. Wait for the human to ask questions, request
revisions, or give approval. Do not proceed until the human explicitly approves.
Before ending your turn, verify every item in this checklist:
Once approved: commit and push (see Git workflow — "After fix plan approved").
2. Execute
Dispatch an engineer-executor subagent with the execute-implementation-plan skill and the
fix plan path. The journal is implementation-journal--fix-{N}.md.
Then dispatch an engineer-reviewer subagent with the review-implementation-execution skill,
the fix journal path, scope whole-plan, and iteration 01. The review artifact is
execution-review--fix-{N}--whole-plan--01.md.
Address all findings from the review:
- Apply trivial findings directly without discussion.
- Dispatch an
engineer-executor to fix significant and critical findings. Flag genuinely
ambiguous ones inline.
- Record the outcome in each finding's
##### Outcome subsection.
- Re-dispatch an
engineer-reviewer at M+1 if changes were substantial. Repeat until the
agent reviewer approves.
If a CHANGELOG.md exists in the repo root, add an entry under ## Unreleased summarising
what was fixed. Use the fix plan's Goal as the basis. Follow the existing entry style in the
file.
STOP — end your turn here.
The execution is ready for human review. Present the execution review to the human. Wait for the
human to ask questions, request revisions, or give approval. Do not proceed until the human
explicitly approves.
Before ending your turn, verify every item in this checklist:
Once approved: commit and push (see Git workflow — "After fix execution approved"), then perform
the final squash onto the parent branch.
3. Report
Report completion with the paths to all new artifacts, a summary of what was changed, and the
squash commit SHA on the parent branch.
