[BLOCKING] Execute skill steps in declared order. NEVER skip, reorder, or merge steps without explicit user approval. [BLOCKING] Before each step or sub-skill call, update task tracking: set in_progress when step starts, set completed when step ends. [BLOCKING] Every completed/skipped step MUST include brief evidence or explicit skip reason. [BLOCKING] If Task tools are unavailable, create and maintain an equivalent step-by-step plan tracker with the same status transitions.

Quick Summary

Goal: Investigate, identify root cause with file:line evidence. Investigation-only — hand off to /fix for implementation.

Workflow:

Classify — Detect bug scenario type (Phase 0) → route to specialized agent
Reproduce — Confirm expected vs actual with evidence
Hypothesize — Form 2-3 ranked theories
Trace — Follow code paths; collect file:line proof per hypothesis
Confirm — Single root cause explains ALL symptoms
Validate — Fresh Eyes round 2 before declaring confirmed
Report — Confidence-tagged finding + hand off to /fix

Key Rules:

NEVER patch symptoms — trace full call chain, fix at owning layer
NEVER report root cause without file:line evidence
NEVER declare confirmed root cause after Round 1 alone (Fresh Eyes required)
Output: confirmed root cause OR "hypothesis, not confirmed" + evidence gaps

Phase 0: Classify Bug Scenario (BLOCKING — Do Before ANY Investigation)

Think: What type of failure is this? Classification routes to the right agent and determines which evidence matters most.

Bug Type	Signals	Specialized Agent
Frontend UI / rendering	Console errors, visual regression, component state	`debugger`
Backend logic / data	Wrong API response, data corruption, validation failure	`debugger`
Cross-service / message bus	Events not propagating, consumer failures, sync lag	`debugger` + graph trace MANDATORY
Performance / memory	Slow queries, OOM, N+1, unbounded result sets	`performance-optimizer`
Security / auth	Access denied, token issues, permission bypass	`security-auditor`

Cross-service bugs: Run graph trace FIRST — grep alone misses implicit bus connections. OOM / memory exhaustion: Check row COUNT before row SIZE. Unbounded query loading thousands of records is the more common cause. Triage: (1) missing DB-level filter? (2) excessive row size?

Debug Mindset (NON-NEGOTIABLE)

Skeptical. Sequential. Every claim needs traced proof, confidence >80%.

NEVER assume first hypothesis correct — verify with actual code traces
Every root cause claim MUST include file:line evidence
Cannot prove root cause → state "hypothesis, not confirmed"
Challenge assumptions: "Is this really the cause?" → trace actual execution path
Challenge completeness: "Other contributing factors?" → check related code paths

Confidence & Evidence Gate

MUST ATTENTION declare Confidence: X% + evidence list + file:line proof for EVERY claim.

Confidence	Meaning	Action
95-100%	Full trace verified	Report as confirmed root cause
80-94%	Main path verified, edge cases uncertain	Report with caveats
60-79%	Partial trace	Report as hypothesis
<60%	Insufficient evidence	DO NOT report — gather more evidence

Investigation Dimensions

Reason through each dimension — state what fails if weak, then apply with evidence.

Dim 1: Reproduce

Think: What exact conditions trigger this? Data state? User action? Timing? Environment delta?

Confirm issue exists with evidence (error message, stack trace, screenshot)
Identify trigger: user action, data state, timing, env difference

Dim 2: Hypothesize

Think: Given symptoms, what are the most plausible failure modes? What would confirm vs contradict each?

Form 2-3 theories ranked by likelihood
Note evidence needed to confirm/contradict each theory before investigating

Dim 3: Trace

Think: Where does bad state ENTER the system — not where it CRASHES? Which layer owns this invariant?

Find entry point (API, UI, job, event)
Follow through handlers/services/transformations
Check error handling paths
Collect file:line evidence per hypothesis
Use graph trace for implicit connections (event handlers, bus consumers)

Dim 4: Confirm

Think: Does this root cause explain ALL symptoms? Are there bypass paths that skip the fix point?

Match evidence to single root cause
Verify root cause explains ALL observed symptoms
Check secondary contributing factors
Verify no bypass paths (direct construction, clone/spread without re-validation, mutations outside model layer)

Dim 5: Report

Output: confirmed root cause + evidence chain
Include: affected files, data flow summary, fix recommendation
Hand off to /fix for implementation

Dependency Tracing (MANDATORY when graph.db exists)

MUST ATTENTION use structural queries — graph reveals ALL callers/consumers grep misses.

# Who calls the buggy function
python .claude/scripts/code_graph query callers_of <function> --json

# Who imports the buggy module
python .claude/scripts/code_graph query importers_of <file> --json

# What tests exist
python .claude/scripts/code_graph query tests_for <function> --json

# Full upstream + downstream context
python .claude/scripts/code_graph trace <suspect-file> --direction both --json

# Callers only (find all trigger points)
python .claude/scripts/code_graph trace <suspect-file> --direction upstream --json

Graph reveals implicit connections (MESSAGE_BUS, event handlers) that propagate issues across services — invisible to grep.

Root Cause Validation (Fresh Eyes Protocol)

NEVER declare confirmed root cause after Round 1 alone. Main agent rationalizes its own findings — a zero-memory sub-agent catches what main agent dismissed.

Round 1 (main agent): Identify root cause + full evidence chain. Write findings to report file.

Round 2 (fresh debugger sub-agent, zero memory of Round 1): Spawn with:

Suspected root cause statement
All file:line evidence collected
Ask: "Does this evidence conclusively prove the stated root cause, or are there gaps?"

Decision:

Sub-agent CONFIRMS → declare confirmed, proceed to /fix
Sub-agent finds GAPS → collect additional evidence, repeat
2 rounds without confirmation → STOP, escalate to user via AskUserQuestion

⚠️ MANDATORY: Post-Fix Verification

After /fix applies changes, /prove-fix MUST be run — builds code proof traces per change with confidence scores. Non-negotiable in all fix workflows.

Anti-Rationalization (Red Flags)

Evasion	Rebuttal
"I see the problem, let me fix it"	Symptoms ≠ root cause. Investigate first.
"Quick fix for now, investigate later"	Quick fixes mask bugs. Find root cause.
"Just try changing X and see"	One hypothesis at a time. Scientific method, not trial and error.
"Already tried 2+ fixes, one more"	3+ failed fixes = STOP. Question the architecture, not the fix.
"The error message is misleading"	Read it again carefully. Error messages are usually right.
"It works on my machine"	Reproduce in the failing environment. Your environment hides bugs.
"This can't be the cause"	Verify with evidence, not intuition. Unlikely causes are still causes.
"It's OOM, must be a large object"	Check row COUNT before row SIZE. Unbounded query > large single row.
"Round 2 fresh agent unnecessary"	Main agent rationalizes its own findings. Zero-memory agent catches dismissals.
"Graph.db not needed for this bug"	Cross-service bugs are invisible to grep. Run trace first.

Workflow Recommendation

MUST ATTENTION — NO EXCEPTIONS: Not in workflow? Use AskUserQuestion:

Activate bugfix workflow (Recommended) — scout → investigate → debug → plan → fix → prove-fix → review → test
Execute /debug-investigate directly — standalone

Next Steps (Standalone only — skip if inside workflow)

MUST ATTENTION use AskUserQuestion after completing. NEVER auto-decide next step:

"Proceed with full workflow (Recommended)" — detect best workflow to continue from here
"/fix" — apply fix based on debug findings
"/plan" — if fix requires planning first
"Skip, continue manually" — user decides

Standalone Review Gate: Outside workflow? MUST create /review-changes task as LAST task.

[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.

docs/project-reference/domain-entities-reference.md — Domain entity catalog, relationships, cross-service sync (read when task involves business entities/models) (read directly when relevant; do not rely on hook-injected conversation text)

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

Reproduce — Confirm the issue exists with evidence (error message, stack trace, screenshot)

Isolate — Narrow to specific file/function/line using binary search + graph trace

Trace — Follow data flow from input to failure point. Read actual code, don't infer.

Hypothesize — Form theory with confidence %. State what evidence supports/contradicts it

Verify — Test hypothesis with targeted grep/read. One variable at a time.

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.

Incremental Result Persistence — MANDATORY for all sub-agents or heavy inline steps processing >3 files.

Before starting: Create report file plans/reports/{skill}-{date}-{slug}.md

After each file/section reviewed: Append findings to report immediately — never hold in memory

Return to main agent: Summary only (per SYNC:subagent-return-contract) with Full report: path

Main agent: Reads report file only when resolving specific blockers

Why: Context cutoff mid-execution loses ALL in-memory findings. Each disk write survives compaction. Partial results are better than no results.

Report naming: plans/reports/{skill-name}-{YYMMDD}-{HHmm}-{slug}.md

Sub-Agent Return Contract — When this skill spawns a sub-agent, the sub-agent MUST return ONLY this structure. Main agent reads only this summary — NEVER requests full sub-agent output inline.
## Sub-Agent Result: [skill-name]

Status: ✅ PASS | ⚠️ PARTIAL | ❌ FAIL
Confidence: [0-100]%

### Findings (Critical/High only — max 10 bullets)

- [severity] [file:line] [finding]

### Actions Taken

- [file changed] [what changed]

### Blockers (if any)

- [blocker description]

Full report: plans/reports/[skill-name]-[date]-[slug].md
Main agent reads Full report file ONLY when: (a) resolving a specific blocker, or (b) building a fix plan. Sub-agent writes full report incrementally (per SYNC:incremental-persistence) — not held in memory.

AI Mistake Prevention — Failure modes to avoid on every task:

Check downstream references before deleting. Deleting components causes documentation and code staleness cascades. Map all referencing files before removal. Verify AI-generated content against actual code. AI hallucinates APIs, class names, and method signatures. Always grep to confirm existence before documenting or referencing. Trace full dependency chain after edits. Changing a definition misses downstream variables and consumers derived from it. Always trace the full chain. Trace ALL code paths when verifying correctness. Confirming code exists is not confirming it executes. Always trace early exits, error branches, and conditional skips — not just happy path. When debugging, ask "whose responsibility?" before fixing. Trace whether bug is in caller (wrong data) or callee (wrong handling). Fix at responsible layer — never patch symptom site. Assume existing values are intentional — ask WHY before changing. Before changing any constant, limit, flag, or pattern: read comments, check git blame, examine surrounding code. Verify ALL affected outputs, not just the first. Changes touching multiple stacks require verifying EVERY output. One green check is not all green checks. Holistic-first debugging — resist nearest-attention trap. When investigating any failure, list EVERY precondition first (config, env vars, DB names, endpoints, DI registrations, data preconditions), then verify each against evidence before forming any code-layer hypothesis. Surgical changes — apply the diff test. Bug fix: every changed line must trace directly to the bug. Don't restyle or improve adjacent code. Enhancement task: implement improvements AND announce them explicitly. Surface ambiguity before coding — don't pick silently. If request has multiple interpretations, present each with effort estimate and ask. Never assume all-records, file-based, or more complex path.

Nested Task Expansion Contract — For workflow-step invocation, the [Workflow] ... row is only a parent container; the child skill still creates visible phase tasks.

Call TaskList first. If a matching active parent workflow row exists, set nested=true and record parentTaskId; otherwise run standalone.

Create one task per declared phase before phase work. When nested, prefix subjects [N.M] $skill-name — phase.

When nested, link the parent with TaskUpdate(parentTaskId, addBlockedBy: [childIds]).

Orchestrators must pre-expand a child skill's phase list and link the workflow row before invoking that child skill or sub-agent.

Mark exactly one child in_progress before work and completed immediately after evidence is written.

Complete the parent only after all child tasks are completed or explicitly cancelled with reason.

Blocked until: TaskList done, child phases created, parent linked when nested, first child marked in_progress.

Project Reference Docs Gate — Run after task-tracking bootstrap and before target/source file reads, grep, edits, or analysis. Project docs override generic framework assumptions.

Identify scope: file types, domain area, and operation.

Required docs by trigger: always docs/project-reference/lessons.md; doc lookup docs-index-reference.md; review code-review-rules.md; backend/CQRS/API backend-patterns-reference.md; domain/entity domain-entities-reference.md; frontend/UI frontend-patterns-reference.md; styles/design scss-styling-guide.md + design-system/README.md; integration tests integration-test-reference.md; E2E e2e-test-reference.md; feature docs/specs feature-docs-reference.md; architecture/new area project-structure-reference.md.

Read every required doc that exists; skip absent docs as not applicable. Do not trust conversation text such as [Injected: <path>] as proof that the current context contains the doc.

Before target work, state: Reference docs read: ... | Missing/not applicable: ....

Blocked until: scope evaluated, required docs checked/read, lessons.md confirmed, citation emitted.

Task Tracking & External Report Persistence — Bootstrap this before execution; then run project-reference doc prefetch before target/source work.

Create a small task breakdown before target file reads, grep, edits, or analysis. On context loss, inspect the current task list first.

Mark one task in_progress before work and completed immediately after evidence; never batch transitions.

For plan/review work, create plans/reports/{skill}-{YYMMDD}-{HHmm}-{slug}.md before first finding.

Append findings after each file/section/decision and synthesize from the report file at the end.

Final output cites Full report: plans/reports/{filename}.

Blocked until: task breakdown exists, report path declared for plan/review work, first finding persisted before the next finding.

Critical Thinking Mindset — Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence >80% to act. Anti-hallucination: Never present guess as fact — cite sources for every claim, admit uncertainty freely, self-check output for errors, cross-reference independently, stay skeptical of own confidence — certainty without evidence root of all hallucination.

Sequential Thinking Protocol — Structured multi-step reasoning for complex/ambiguous work. Use when planning, reviewing, debugging, or refining ideas where one-shot reasoning is unsafe.

Trigger when: complex problem decomposition · adaptive plans needing revision · analysis with course correction · unclear/emerging scope · multi-step solutions · hypothesis-driven debugging · cross-cutting trade-off evaluation.

Format (explicit mode — visible thought trail):

Thought N/M: [aspect] — one aspect per thought, state assumptions/uncertainty

Thought N/M [REVISION of Thought K]: ... — when prior reasoning invalidated; state Original / Why revised / Impact

Thought N/M [BRANCH A from Thought K]: ... — explore alternative; converge with decision rationale

Thought N/M [HYPOTHESIS]: ... then [VERIFICATION]: ... — test before acting

Thought N/N [FINAL] — only when verified, all critical aspects addressed, confidence >80%

Mandatory closers: Confidence % stated · Assumptions listed · Open questions surfaced · Next action concrete.

Stop conditions: confidence <80% on any critical decision → escalate via AskUserQuestion · ≥3 revisions on same thought → re-frame the problem · branch count >3 → split into sub-task.

Implicit mode: apply methodology internally without visible markers when adding markers would clutter the response (routine work where reasoning aids accuracy).

Deep-dive: see /sequential-thinking skill (.claude/skills/sequential-thinking/SKILL.md) for worked examples (api-design, debug, architecture), advanced techniques (spiral refinement, hypothesis testing, convergence), and meta-strategies (uncertainty handling, revision cascades).

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

Search 3+ similar patterns (grep/glob) — cite file:line evidence

Read existing files in target area — understand structure, base classes, conventions

Run python .claude/scripts/code_graph trace <file> --direction both --json when .code-graph/graph.db exists

Map dependencies via connections or callers_of — know what depends on your target

Write investigation to .ai/workspace/analysis/ for non-trivial tasks (3+ files)

Re-read analysis file before implementing — never work from memory alone

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.

Cite file:line, grep results, or framework docs for EVERY claim

Declare confidence: >80% act freely, 60-80% verify first, <60% DO NOT recommend

Cross-service validation required for architectural changes

"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: [...]."

Cross-Service Check — Microservices/event-driven: MANDATORY before concluding investigation, plan, spec, or feature doc. Missing downstream consumer = silent regression.

Boundary Grep terms
Event producers Publish, Dispatch, Send, emit, EventBus, outbox, IntegrationEvent
Event consumers Consumer, EventHandler, Subscribe, @EventListener, inbox
Sagas/orchestration Saga, ProcessManager, Choreography, Workflow, Orchestrator
Sync service calls HTTP/gRPC calls to/from other services
Shared contracts OpenAPI spec, proto, shared DTO — flag breaking changes
Data ownership Other service reads/writes same table/collection → Shared-DB anti-pattern

Per touchpoint: owner service · message name · consumers · risk (NONE / ADDITIVE / BREAKING).

BLOCKED until: Producers scanned · Consumers scanned · Sagas checked · Contracts reviewed · Breaking-change risk flagged

Estimation Framework — Bottom-up first; SP DERIVED; output min-max range when likely ≥3d. Stack-agnostic. Baseline: 3-5yr dev, 6 productive hrs/day. AI estimate assumes Claude Code + project context.

Method:

Blast Radius pass (below) — drives code AND test cost

Decompose phases → hours/phase → bottom_up_hours = Σ phase_hours

likely_days = ceil(bottom_up_hours / 6) × productivity_factor

Sum Risk Margin (base + add-ons) → max_days = likely_days × (1 + margin)

min_days = likely_days × 0.9

Output as range when likely_days ≥3; single point allowed <3 (still record margin)

man_days_ai = same range × AI speedup

story_points DERIVED from likely_days via SP-Days — NEVER driver. Disagreement >50% → trust bottom-up

Productivity factor: 0.8 strong scaffolding+codegen+AI hooks · 1.0 mature default · 1.2 weak patterns · 1.5 greenfield

Cost Driver Heuristic (apply BEFORE work-type row):

UI dominates in CRUD/business apps — 1.5-3x backend (states, validation, responsive, a11y, polish)

Backend dominates ONLY: multi-aggregate invariants, cross-service contracts, schema migrations, heavy query/perf, new event flows

Reuse-vs-Create axis (PRIMARY lever, per layer):

UI tier Cost
Reuse component on existing screen 0.1-0.3d
Add control/column to existing screen 0.3-0.8d
Compose components into NEW screen 1-2d
NEW screen, custom layout/states/validation 2-4d
NEW shared/common component (themed, tested) 3-6d+

Backend tier Cost
Reuse query/handler from new place 0.1-0.3d
Small update existing handler/entity 0.3-0.8d
NEW query on existing repo/model 0.5-1d
NEW command/handler on existing aggregate (additive) 1-2d
NEW aggregate/entity (repo, validation, events) 2-4d
NEW cross-service contract OR schema migration 2-4d each
Multi-aggregate invariant / heavy domain rule 3-5d

Rule: Sum tiers across UI+backend+tests, apply productivity factor. Reuse short-circuits tiers — call out.

Test-Scope drivers (compute test_count EXPLICITLY — "+tests" hand-wave is #1 failure):

Driver Count
Happy-path journeys 1 per story / AC main flow
State-machine transitions reachable transitions × allowed actors
Multi-entity state combos state(A) × state(B) — REACHABLE only, not Cartesian
Authorization matrix (owner, non-owner, elevated, unauth) × each mutation
Validation rules 1 per required field / boundary / format / cross-field
UI states (per new screen/dialog) happy, loading, empty, error, partial — present only
Negative paths / invariants 1 per violatable business rule

Test tier (Trad, incl. setup+assert+flake) Cost
1-5 cases, fixtures reused 0.3-0.5d
6-12 cases, 1 new fixture 0.5-1d
13-25 cases, multi-entity setup 1-2d
26-50 cases OR new state-machine coverage 2-3d
>50 cases OR full E2E journey 3-5d

Test multipliers: new fixture/seed harness +0.5d · cross-service/bus assertion +0.3d each · UI E2E ×1.5 · each new role +1-2 cases

Blast Radius (mandatory pre-pass — affects code AND test):

Files/components directly modified — count

Of those, "complex" (>500 LOC, multi-handler, central, frequently-modified) — count

Downstream consumers (callers, event subscribers, cross-service) — list

Shared/common code touched (multi-app blast) — yes/no

Regression scope — areas needing re-test

Rule: Complex touch → add risk_factors. Each downstream consumer → +1-3 regression cases. Blast >5 areas OR >2 complex → re-evaluate SPLIT before estimating.

Risk Margin (drives max bound):

likely_days Base margin
<1d trivial +10%
1-2d small additive +20%
3-4d real feature +35%
5-7d large +50%
8-10d very large +75%
>10d +100% AND flag SHOULD SPLIT

Risk-factor add-ons (additive — enumerate in risk_factors):

Factor +margin
touches-complex-existing-feature (>500 LOC, multi-handler, central) +20%
cross-service-contract change +25%
schema-migration-on-populated-data +25%
new-tech-or-unfamiliar-pattern +30%
regression-fan-out (≥3 downstream areas re-test) +20%
performance-or-latency-critical +20%
concurrency-race-event-ordering +25%
shared-common-code (multi-consumer/multi-app) +25%
unclear-requirements-or-design +30%

Collapse rule: total margin >100% → STOP, split (padding past 2x is dishonesty). Margin <15% on likely_days ≥5 → under-estimated, widen.

Work-Type Caps (hard ceilings on likely_days):

Work type Max SP Max likely
Single field / config flag / style fix 1 0.5d
Add property to existing model + bind to existing UI 2 1d
Additive endpoint + minor UI control (button/menu/column), reuses fixtures 3 2-3d
Additive endpoint + NEW UI surface OR additive multi-layer + new domain rule + 2+ test files 5 3-5d
NEW model/aggregate OR migration OR cross-module contract OR heavy test (>1.5d) OR NEW UI + non-trivial backend 8 5-7d
NEW UI surface + (NEW aggregate OR migration OR cross-service contract) 13 SHOULD split
Cross-service contract + migration combined 13 SHOULD split
Beyond 21 MUST split

SP→Days (validation only): 1=0.5d/0.25d · 2=1d/0.35d · 3=2d/0.65d · 5=4d/1.0d · 8=6d/1.5d · 13=10d/2.0d (Trad/AI likely) AI speedup: SP 1≈2x · 2-3≈3x · 5-8≈4x · 13+≈5x. AI cost = (code_gen × 1.3) + (test_gen × 1.3) (30% review overhead).

MANDATORY frontmatter:
story_points: <n>
complexity: low | medium | high | critical
man_days_traditional: '<min>-<max>d' # range when likely ≥3d; '<N>d' when <3d
man_days_ai: '<min>-<max>d'
risk_margin_pct: <n> # base + add-ons
risk_factors: [touches-complex-existing-feature, regression-fan-out] # closed-list from add-ons; [] if none
blast_radius:
    touched_areas: <n>
    complex_touched: <n>
    downstream_consumers: [list or count]
    shared_common_code: yes | no
estimate_scope_included: [code, integration-tests, frontend, i18n, docs]
estimate_scope_excluded: [unit-tests, e2e, perf, deployment, code-review-rounds]
estimate_reasoning: |
    5-7 lines covering:
    (a) UI tier — row applied
    (b) Backend tier — row applied
    (c) Test scope — case breakdown by driver, file count, fixtures, tier row
    (d) Cost driver — dominant tier + why
    (e) Blast radius — touched, complex, regression scope
    (f) Risk factors — list driving margin; why not larger/smaller
    Example: "UI: compose Form/Table/Dialog → NEW screen (~1.5d). Backend: NEW command on existing aggregate,
    reuses validation+repo (~1d). Tests: 4 transitions × 2 actors + 3 validation + 2 UI states = 13 cases,
    1 new fixture → tier 13-25 ~1.5d. Driver: UI composition + new states. Blast: 4 areas, 1 complex.
    Risk: base 35% + touches-complex +20% = 55% → max 3.9d → range 2.5-4d."
Sanity self-check:

likely_days ≥3d and single-point? → reject, must be range

Margin <15% on likely_days ≥5d? → under-estimated, widen

Margin >100%? → STOP, split instead of buffer

Complex existing feature touched, no regression budget in (c)? → reject

Blast >5 areas OR >2 complex, no split discussion? → reject

Purely additive on existing model AND existing UI? → cap SP 3 unless tests >1.5d

NEW UI surface (page/complex form/dashboard)? → SP 5+ even if backend one endpoint

Backend cross-service / migration / multi-aggregate? → SP 8+ regardless of UI

bottom_up_hours / 6 vs SP-Days disagreement >50%? → trust bottom-up, downgrade SP

Without tests, SP drops ≥1 bucket? → tests dominate; state explicitly

Reasoning called out UI vs backend vs blast vs risk factors? → if missing, add

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

Confidence drops below 60% on any critical decision

Changes would affect >20 files (blast radius too large)

Cross-service boundary is being crossed

Security-sensitive code (auth, crypto, PII handling)

Breaking change detected (interface, API contract, DB schema)

Test coverage would decrease after changes

Approach requires technology/pattern not in the project

NEVER proceed past a red flag without explicit user approval.

Fix-Layer Accountability — NEVER fix at the crash site. Trace the full flow, fix at the owning layer.

AI default behavior: see error at Place A → fix Place A. This is WRONG. The crash site is a SYMPTOM, not the cause.

MANDATORY before ANY fix:

Trace full data flow — Map the complete path from data origin to crash site across ALL layers (storage → backend → API → frontend → UI). Identify where the bad state ENTERS, not where it CRASHES.

Identify the invariant owner — Which layer's contract guarantees this value is valid? That layer is responsible. Fix at the LOWEST layer that owns the invariant — not the highest layer that consumes it.

One fix, maximum protection — Ask: "If I fix here, does it protect ALL downstream consumers with ONE change?" If fix requires touching 3+ files with defensive checks, you are at the wrong layer — go lower.

Verify no bypass paths — Confirm all data flows through the fix point. Check for: direct construction skipping factories, clone/spread without re-validation, raw data not wrapped in domain models, mutations outside the model layer.

BLOCKED until: - [ ] Full data flow traced (origin → crash) - [ ] Invariant owner identified with file:line evidence - [ ] All access sites audited (grep count) - [ ] Fix layer justified (lowest layer that protects most consumers)

Anti-patterns (REJECT these):

"Fix it where it crashes" — Crash site ≠ cause site. Trace upstream.

"Add defensive checks at every consumer" — Scattered defense = wrong layer. One authoritative fix > many scattered guards.

"Both fix is safer" — Pick ONE authoritative layer. Redundant checks across layers send mixed signals about who owns the invariant.

MUST ATTENTION apply critical thinking — every claim needs traced proof, confidence >80% to act. Anti-hallucination: never present guess as fact.

MUST ATTENTION apply sequential-thinking — multi-step Thought N/M, REVISION/BRANCH/HYPOTHESIS markers, confidence % closer; see /sequential-thinking skill.

MUST ATTENTION apply AI mistake prevention — holistic-first debugging, fix at responsible layer, surface ambiguity before coding, re-read files after compaction.

MANDATORY Bootstrap task tracking before target work; transition one task at a time.
MANDATORY Persist plan/review findings to plans/reports/ incrementally and synthesize from disk.

MANDATORY After task-tracking bootstrap and before target/source work, read required project-reference docs and cite Reference docs read: ....
MANDATORY Always include lessons.md; project conventions override generic defaults.

MANDATORY Parent workflow rows do not replace child phase tracking; expand phases and link the parent when nested.
MANDATORY Orchestrators pre-expand child skill phases before invocation; use [N.M] $skill-name — phase prefixes and one-in_progress discipline.

Prompt-Enhance Closing Anchors

IMPORTANT MUST ATTENTION follow declared step order for this skill; NEVER skip, reorder, or merge steps without explicit user approval IMPORTANT MUST ATTENTION for every step/sub-skill call: set in_progress before execution, set completed after execution IMPORTANT MUST ATTENTION every skipped step MUST include explicit reason; every completed step MUST include concise evidence IMPORTANT MUST ATTENTION if Task tools unavailable, maintain an equivalent step-by-step plan tracker with synchronized statuses

Closing Reminders

MUST ATTENTION Phase 0 FIRST — classify bug type, route to specialized agent (performance-optimizer / security-auditor) before any investigation MUST ATTENTION NEVER fix at crash site — trace full data flow, fix at invariant-owning layer MUST ATTENTION NEVER report root cause without file:line evidence; Confidence <60% = DO NOT recommend MUST ATTENTION NEVER declare confirmed root cause after Round 1 alone — Fresh Eyes Protocol required MUST ATTENTION run graph trace when graph.db exists — reveals bus consumers and event handlers grep cannot see MUST ATTENTION OOM → check row COUNT before row SIZE; 3+ failed fixes → STOP, escalate to user MUST ATTENTION TaskCreate before starting; /prove-fix MUST run after /fix applies changes

Anti-Rationalization:

Evasion	Rebuttal
"Too simple for Phase 0"	Root cause assumptions waste more time than classification. Apply anyway.
"Already traced, no graph needed"	Show `file:line` evidence. No proof = no trace.
"Round 2 fresh agent wastes time"	Main agent rationalizes its own mistakes. Zero-memory agent is non-negotiable.
"This is a frontend bug, no graph"	Frontend → backend → bus chains exist. Run trace first.

[TASK-PLANNING] Before acting, analyze task scope and systematically break it into small todo tasks and sub-tasks using TaskCreate.

name	debug-investigate
version	2.0.0
description	[Fix & Debug] Use when bugfix workflow reaches debug step.