Agent Skills: fix-parallel

[IMPORTANT] Use TaskCreate to break ALL work into small tasks BEFORE starting — including tasks for each file read. This prevents context loss from long files. For simple tasks, AI MUST ATTENTION ask user whether to skip.

Understand Code First — HARD-GATE: Do NOT write, plan, or fix until you READ existing code.

1. Search 3+ similar patterns (grep/glob) — cite file:line evidence
2. Read existing files in target area — understand structure, base classes, conventions
3. Run python .claude/scripts/code_graph trace <file> --direction both --json when .code-graph/graph.db exists
4. Map dependencies via connections or callers_of — know what depends on your target
5. Write investigation to .ai/workspace/analysis/ for non-trivial tasks (3+ files)
6. Re-read analysis file before implementing — never work from memory alone
7. NEVER invent new patterns when existing ones work — match exactly or document deviation

BLOCKED until: - [ ] Read target files - [ ] Grep 3+ patterns - [ ] Graph trace (if graph.db exists) - [ ] Assumptions verified with evidence

Evidence-Based Reasoning — Speculation is FORBIDDEN. Every claim needs proof.

1. Cite file:line, grep results, or framework docs for EVERY claim
2. Declare confidence: >80% act freely, 60-80% verify first, <60% DO NOT recommend
3. Cross-service validation required for architectural changes
4. "I don't have enough evidence" is valid and expected output

BLOCKED until: - [ ] Evidence file path (file:line) - [ ] Grep search performed - [ ] 3+ similar patterns found - [ ] Confidence level stated

Forbidden without proof: "obviously", "I think", "should be", "probably", "this is because" If incomplete → output: "Insufficient evidence. Verified: [...]. Not verified: [...]."

• docs/project-reference/domain-entities-reference.md — Domain entity catalog, relationships, cross-service sync (read when task involves business entities/models) (content auto-injected by hook — check for [Injected: ...] header before reading)

Estimation — Modified Fibonacci: 1(trivial) → 2(small) → 3(medium) → 5(large) → 8(very large) → 13(epic, SHOULD split) → 21(MUST ATTENTION split). Output story_points and complexity in plan frontmatter. Complexity auto-derived: 1-2=Low, 3-5=Medium, 8=High, 13+=Critical.

Red Flag Stop Conditions — STOP and escalate to user via AskUserQuestion when:

1. Confidence drops below 60% on any critical decision
2. Changes would affect >20 files (blast radius too large)
3. Cross-service boundary is being crossed
4. Security-sensitive code (auth, crypto, PII handling)
5. Breaking change detected (interface, API contract, DB schema)
6. Test coverage would decrease after changes
7. Approach requires technology/pattern not in the project

NEVER proceed past a red flag without explicit user approval.

Skill Variant: Variant of /fix — parallel multi-issue resolution using subagents.

Quick Summary

Goal: Fix multiple independent issues simultaneously using parallel fullstack-developer subagents.

Workflow:

1. Triage — Classify issues and verify independence (no shared files)
2. Assign — Distribute issues to parallel subagents with strict file ownership
3. Execute — Subagents fix issues independently
4. Merge — Review and integrate all fixes

Key Rules:

• Debug Mindset: every claim needs file:line evidence
• Issues MUST ATTENTION be independent (no overlapping file modifications)
• Each subagent owns specific files; no cross-boundary edits

Root Cause Debugging — Systematic approach, never guess-and-check.

1. Reproduce — Confirm the issue exists with evidence (error message, stack trace, screenshot)
2. Isolate — Narrow to specific file/function/line using binary search + graph trace
3. Trace — Follow data flow from input to failure point. Read actual code, don't infer.
4. Hypothesize — Form theory with confidence %. State what evidence supports/contradicts it
5. Verify — Test hypothesis with targeted grep/read. One variable at a time.
6. Fix — Address root cause, not symptoms. Verify fix doesn't break callers via graph connections

NEVER: Guess without evidence. Fix symptoms instead of cause. Skip reproduction step.

Frontend/UI Context (if applicable)

When this task involves frontend or UI changes,

UI System Context — For ANY task touching .ts, .html, .scss, or .css files:

MUST ATTENTION READ before implementing:

1. docs/project-reference/frontend-patterns-reference.md — component base classes, stores, forms
2. docs/project-reference/scss-styling-guide.md — BEM methodology, SCSS variables, mixins, responsive
3. docs/project-reference/design-system/README.md — design tokens, component inventory, icons

Reference docs/project-config.json for project-specific paths.

• Component patterns: docs/project-reference/frontend-patterns-reference.md
• Styling/BEM guide: docs/project-reference/scss-styling-guide.md
• Design system tokens: docs/project-reference/design-system/README.md

Debug Mindset (NON-NEGOTIABLE)

Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence percentages (Idea should be more than 80%).

• Do NOT assume the first hypothesis is correct — verify with actual code traces
• Every root cause claim must include file:line evidence
• If you cannot prove a root cause with a code trace, state "hypothesis, not confirmed"
• Question assumptions: "Is this really the cause?" → trace the actual execution path
• Challenge completeness: "Are there other contributing factors?" → check related code paths
• No "should fix it" without proof — verify the fix addresses the traced root cause

⚠️ MANDATORY: Confidence & Evidence Gate

MANDATORY IMPORTANT MUST ATTENTION declare Confidence: X% with evidence list + file:line proof for EVERY claim. 95%+ recommend freely | 80-94% with caveats | 60-79% list unknowns | <60% STOP — gather more evidence.

⚠️ Validate Before Fix (NON-NEGOTIABLE): After root cause analysis + plan creation, MUST ATTENTION present findings + proposed fix plan to user via AskUserQuestion and get explicit approval BEFORE any code changes. No silent fixes.

Ultrathink parallel to fix: <issues>$ARGUMENTS</issues>

IMPORTANT: Activate needed skills. Ensure token efficiency. Sacrifice grammar for concision.

Workflow

1. Issue Analysis

• Use debugger subagent to analyze root causes
• Use /scout-ext to find related files
• Categorize issues by scope/area (frontend, backend, auth, payments, etc.)
• Identify dependencies between issues
• External Memory: Each parallel agent writes findings to .ai/workspace/analysis/{issue-name}-{agent}.analysis.md. Main agent re-reads all before coordinating fixes.

2. Parallel Fix Planning

• Trigger /plan-parallel <detailed-fix-instructions> for parallel-executable fix plan
• Wait for plan with dependency graph, execution strategy, file ownership matrix
• Group independent fixes for parallel execution
• Sequential fixes for dependent issues
• 🛑 Present root cause + fix plan → AskUserQuestion → wait for user approval before launching agents.

3. Parallel Fix Implementation

• Read plan.md for dependency graph
• Launch multiple fullstack-developer agents in PARALLEL for independent fixes
  • Example: "Fix auth + Fix payments + Fix UI" → launch 3 agents simultaneously
  • Pass phase file path: {plan-dir}/phase-XX-*.md
  • Include environment info
• Wait for all parallel fixes complete before dependent fixes
• Sequential fixes: launch one agent at a time

Subagent Context Discipline:

• Provide full task text — paste task content into subagent prompt; don't make subagent read plan file
• "Ask questions before starting" — subagent should surface uncertainties before implementing
• Self-review before reporting — subagent checks completeness, quality, YAGNI before returning results

4. Testing

• Use tester subagent for full test suite
• NO fake data/mocks/cheats
• Verify all issues resolved
• If fail: use debugger, fix, repeat

5. Code Review

Two-Stage Task Review — Both stages MUST ATTENTION complete before marking task done.

Stage 1: Self-review — Immediately after implementation:

• Requirements met? No regressions? Code quality acceptable?

Stage 2: Cross-review — Via code-reviewer subagent:

• Catches blind spots, convention drift, missed edge cases

NEVER skip Stage 2. Self-review alone misses 40%+ of issues.

1. First: dispatch `spec-compliance-reviewer` to verify each fix matches its spec
2. Only after spec passes: dispatch `code-reviewer` for quality review

• Verify fixes don't introduce regressions
• If critical issues: fix, retest

6. Project Management & Docs

• If approved: use project-manager + docs-manager in parallel
• Update plan files, docs, roadmap
• If rejected: fix and repeat

7. Prove Fix

• MANDATORY: Run /prove-fix for EACH parallel fix
• Build code proof traces per change with confidence scores
• If any change scores < 80%, return to debug for that fix

8. Final Report

• Summary of all fixes from parallel phases
• Verification status per issue (include prove-fix confidence scores)
• Ask to commit (use git-manager if yes)

Example: Fix 1 (auth) + Fix 2 (payments) + Fix 3 (UI) → Launch 3 fullstack-developer agents → Wait → Prove each fix → Fix 4 (integration) sequential

Next Steps (Standalone: MUST ATTENTION ask user via AskUserQuestion. Skip if inside workflow.)

MANDATORY IMPORTANT MUST ATTENTION — NO EXCEPTIONS: If this skill was called outside a workflow, you MUST ATTENTION use AskUserQuestion to present these options. Do NOT skip because the task seems "simple" or "obvious" — the user decides:

• "Proceed with full workflow (Recommended)" — I'll detect the best workflow to continue from here (fixes applied). This ensures prove-fix, review, testing, and docs steps aren't skipped.
• "/prove-fix" — Prove fix correctness with code traces
• "/test" — Run tests to verify fixes
• "Skip, continue manually" — user decides

If already inside a workflow, skip — the workflow handles sequencing.

Closing Reminders

• MANDATORY IMPORTANT MUST ATTENTION break work into small todo tasks using TaskCreate BEFORE starting
• MANDATORY IMPORTANT MUST ATTENTION search codebase for 3+ similar patterns before creating new code
• MANDATORY IMPORTANT MUST ATTENTION cite file:line evidence for every claim (confidence >80% to act)
• MANDATORY IMPORTANT MUST ATTENTION add a final review todo task to verify work quality
• MANDATORY IMPORTANT MUST ATTENTION STOP after 3 failed fix attempts — report outcomes, ask user before #4 MANDATORY IMPORTANT MUST ATTENTION READ the following files before starting: <!-- SYNC:understand-code-first:reminder -->
• MANDATORY IMPORTANT MUST ATTENTION search 3+ existing patterns and read code BEFORE any modification. Run graph trace when graph.db exists. <!-- /SYNC:understand-code-first:reminder --> <!-- SYNC:evidence-based-reasoning:reminder -->
• MANDATORY IMPORTANT MUST ATTENTION cite file:line evidence for every claim. Confidence >80% to act, <60% = do NOT recommend. <!-- /SYNC:evidence-based-reasoning:reminder --> <!-- SYNC:estimation-framework:reminder -->
• MANDATORY IMPORTANT MUST ATTENTION include story_points and complexity in plan frontmatter. SP > 8 = split. <!-- /SYNC:estimation-framework:reminder --> <!-- SYNC:red-flag-stop-conditions:reminder -->
• MANDATORY IMPORTANT MUST ATTENTION STOP after 3 failed fix attempts. Report all attempts, ask user before continuing. <!-- /SYNC:red-flag-stop-conditions:reminder --> <!-- SYNC:ui-system-context:reminder -->
• MANDATORY IMPORTANT MUST ATTENTION read frontend-patterns-reference, scss-styling-guide, design-system/README before any UI change. <!-- /SYNC:ui-system-context:reminder -->