| name | fix-pr-delivery |
| description | Streamlined delivery flow for fix PRs created during adversarial refinement, formal hardening, and convergence. Same rigor as story PRs (worktree, AI review, security review) but skips stubs, Red Gate, and wave integration gates.
|
Fix PR Delivery Flow
When This Skill Runs
When adversarial refinement, formal hardening, or convergence produce findings
that require code fixes on the merged develop branch. Fix tasks are named
FIX-P[phase]-NNN (e.g., FIX-P4-001, FIX-P5-003).
Differences from Story PR Delivery
| Aspect | Story PR | Fix PR |
|---|
| Branch prefix | feature/STORY-NNN | fix/FIX-P4-NNN |
| PR title | feat(STORY-NNN): ... | fix(FIX-P4-NNN): ... |
| Demo required | Always (per AC) | Only if behavior-changing |
| PR description | Full template with diagrams | Streamlined -- links to finding |
| Wave gate after | Yes (wave integration gate) | No -- fix PRs merge individually |
| Stubs + Red Gate | Yes (two-step) | No -- fix goes directly to implementation |
Workflow
Step 1: Orchestrator Creates Fix Task
When a phase finding requires a code fix, the orchestrator creates a fix task:
Finding: [finding ID from adversarial/hardening/convergence]
Fix Task: FIX-P[phase]-NNN
Description: [one-line description of what needs fixing]
Source: [adversarial | hardening | convergence]
Severity: [CRITICAL | HIGH | MEDIUM | LOW]
Step 2: DevOps-Engineer Creates Worktree
git worktree add .worktrees/FIX-P4-001 -b fix/FIX-P4-001 develop
Step 3: Implementer Fixes in Worktree
The implementer works in .worktrees/FIX-P[phase]-NNN/:
- Read the finding report for context
- Apply the fix
- Run tests -- all must pass
- Commit with message:
fix(FIX-P[phase]-NNN): [description]
Step 4: Demo Recording (Conditional)
Demo-recorder records a demo ONLY if the fix is behavior-changing:
- Behavior-changing fixes: Changes to output, error messages, CLI flags,
API responses, security restrictions, or any user-observable behavior.
Record a demo showing the corrected behavior.
- Transparent fixes: Refactoring, performance improvements, internal error
handling, code style. No demo needed.
Step 5: Push Branch
cd .worktrees/FIX-P[phase]-NNN/
git push --force-with-lease origin fix/FIX-P[phase]-NNN
Step 6: PR-Manager Creates PR
Create a streamlined PR description:
## Fix: FIX-P[phase]-NNN
**Finding:** [link to finding report and finding ID]
**Phase:** [4 | 5 | 6]
**Severity:** [CRITICAL | HIGH | MEDIUM | LOW]
### What Changed
[Brief description of the fix]
### Why
[Link to the finding that triggered this fix]
### Testing
- [ ] All existing tests pass
- [ ] New test added for the specific finding (if applicable)
- [ ] Demo recorded (if behavior-changing)
pr-manager spawns github-ops to create the PR, and spawns pr-reviewer to review:
Step 7: PR-Reviewer Reviews Fix Diff
The pr-reviewer (4th model family) reviews the fix PR diff:
- Same 8-item checklist as story PRs
- Smaller scope -- only the fix changes
- Focus on: does the fix actually address the finding?
Step 8: Security Review (Conditional)
If the fix is security-related (CWE/OWASP finding, dependency vulnerability,
auth/authz change):
security-reviewer (T2, NO IMPL REASONING):
Input: Fix PR diff only
Action: Verify the fix addresses the security finding without
introducing new vulnerabilities
Output: APPROVE / REQUEST_CHANGES via github-ops
Step 9: Review Convergence
Max 10 review cycles:
- PR-reviewer posts findings
- PR-manager triages findings, routes to implementer
- Implementer fixes in worktree, pushes
- PR-reviewer re-reviews
- Repeat until APPROVE or 10 cycles exhausted
Step 10: Merge and Cleanup
pr-manager spawns github-ops to merge, then verifies remote branch deletion,
then orchestrator spawns devops-engineer and state-manager for cleanup:
github-ops: "cd <project-path> && gh pr merge --squash --delete-branch"
# Post-merge: verify branch is actually deleted — --delete-branch is async
# (not guaranteed under merge queues; see cli/cli#9073).
# Full hardened sequence (pr-manager.md Step 8 is authoritative):
# 1. Confirm PR state is MERGED (not queued): gh pr view --json state,mergeStateStatus
# 2. Check isCrossRepository: gh pr view --json isCrossRepository,headRepositoryOwner,headRefName
# If fork PR → skip origin deletion (branch lives on contributor's fork).
# 3. Exact-ref check: git ls-remote --exit-code origin refs/heads/<branch>
# (exit code 2 = not found = deleted; avoids prefix-match false positives)
# 4. If still present: wait 5–10 seconds between re-checks, bounded retry (up to 3),
# then force-delete: git push origin --delete <branch> and re-verify
# (idempotent — already-gone/404 is success).
# 5. If branch-protection blocks deletion: log warning and proceed (not fatal).
devops-engineer: "cd <project-path> && git worktree remove .worktrees/FIX-P[phase]-NNN"
state-manager: "Update STATE.md with FIX-P[phase]-NNN completion — merge status, PR number, timestamp"
Source-Specific Re-Verification After Fix PRs Merge
After fix PRs merge to develop, re-verification depends on the source phase:
Adversarial Fixes
Re-run adversary with fresh context -- full adversarial pass on develop.
Hardening Fixes
- Adversarial "lite" review first: Adversary (fresh context) reviews ONLY
the fix diffs, not a full codebase re-review.
- Re-run ONLY failing checks:
- If Kani VP-003 failed: re-run only VP-003 (locked VPs are not re-run)
- If fuzz target crashed: re-run only that fuzz target
- Do NOT re-run already-passing checks (mutation, security, purity)
- If still fails: another fix cycle (max 10 per finding)
- If passes: hardening gate clears
Convergence Fixes
Route to the specific failing dimension:
- Implementation not converged -> another adversarial pass
- Holdout not converged -> re-evaluate holdout scenarios, fix, re-evaluate
- Tests not converged -> additional testing
- Verification not converged -> additional formal verification
Then re-run convergence assessment.
Quality Gate Criteria
