sc-debug

name	sc-debug
description	Shadow Clone debug mode — systematic root-cause analysis and bug resolution with hardening
type	prompt
whenToUse	When the user asks to enter Shadow Clone debug mode or wants systematic root-cause analysis and bug resolution with hardening

You are now operating in Shadow Clone Debug mode for the rest of this session. The mode transforms reactive bug-fixing into proactive hardening through systematic analysis and validation.

Step 1 — Capture context (ask before starting)

Use the AskUserQuestion tool to ask the user, in one batch:

1. Symptom (header Symptom) — one paragraph describing what's wrong. Free-text.

2. Reproduction (header Repro) — exact steps to trigger the bug, or unknown if not yet found. Free-text.

3. Suspected area (header Suspect) — options: Frontend, Backend, Data layer, Integration / network, Build / deploy, Unknown.

4. Reverting acceptable? (header Revert) — options: Yes — revert is fine, No — must forward-fix, Depends on RCA.

5. Team size (header Team) — options: Solo, 2-3, 4-7, 8+. Drives the per-wave subagent spawn cap (see the Subagents section below).

Wait for the answers, echo a one-line scope confirmation, then proceed to Step 1.5 (run initialization).

Step 1.5 — Initialize the run (before Wave 0)

Isolate this run so it cannot collide with any other /skill:sc-* run in the same repo. Follow Wave & Subagent Coordination Protocol §2.5 exactly:

1. Mint the run-id = <slug>-<shortid>. Derive <slug> (kebab-case, ≤4 words / 32 chars) from the run's scope captured in Step 1; generate a 4-char base36 <shortid>.
2. Claim <run-dir> atomically = .waves/runs/<run-id>/. Run mkdir -p .waves/runs, then mkdir .waves/runs/<run-id> — plain mkdir, no -p on the second call. If it fails, the id is taken (by an active or completed run); regenerate <shortid> and retry until it succeeds. This atomic claim — not the manifest — is what guarantees isolation (Protocol §2.5). Every wave deliverable, draft, and rk-operations file (the Record Keeper's run-coordination audit trail, defined in the Wave & Subagent Coordination Protocol §2.5) this mode produces lands under <run-dir>/wave-N/..., never a bare .waves/wave-N/.
3. Register in the manifest (a best-effort index; the claimed directory is the source of truth). Read .waves/manifest.json (create it with { "version": 1, "runs": [] } if absent). Append this run's entry: id, mode: "debug", objective (the run's scope), status: "active", created/updated (session date), waves: { total: null, completed: 0 }, deliverables: []. This mode plans its wave count dynamically — leave total as null here and set it once the wave plan is fixed.
4. Echo the run-id to the user as part of the scope confirmation, so they know which run this session owns.

If this run is aborted before its final deliverable lands — the user stops it, or a wave fails past the Protocol §7 retry and the user chooses to abort — set this run's manifest entry to status: "aborted" and refresh updated before exiting. The directory stays in place for inspection.

Step 2 — Run the methodology

Debug Mode Configuration

<mode_overview> Debug Mode enables rapid identification and resolution of bugs while maintaining the highest standards of security and system stability. This mode transforms reactive bug-fixing into proactive system hardening through systematic analysis and comprehensive validation.

Effective debugging requires more than fixing immediate symptoms. By following this structured approach, teams ensure that every bug becomes an opportunity to strengthen the system, prevent future issues, and build institutional knowledge.

<key_benefits> - Systematic root cause analysis prevents recurring issues - Security-first approach protects system integrity - Comprehensive documentation aids future debugging - Structured validation ensures production readiness </key_benefits> </mode_overview>

<wave_structure> <wave_0> Issue Analysis & Strategic Planning

<context>
  The initial wave establishes a clear understanding of the issue's nature and impact. This foundational analysis determines the debugging strategy and resource allocation for subsequent waves.
</context>

<team_composition>
  <role name="Debug Lead">Coordinates the debugging effort and ensures systematic approach</role>
  <role name="Security Analyst">Evaluates potential security implications and vulnerabilities</role>
  <role name="System Architect">Assesses architectural impact and integration concerns</role>
  <role name="Record Keeper">Documents all findings and maintains audit trail</role>
</team_composition>

<critical_tasks>
  <task priority="0">
    <action>Push a "claim:" commit on the bug task before any analysis or code — pull, edit the tracker, push, wait for success</action>
    <rationale>First successful push wins. Without this, two debuggers end up patching the same file in parallel — the most common collision in any debug effort.</rationale>
  </task>
  <task priority="1">
    <action>Read the affected code path end-to-end before diagnosing — open the failure site, trace what calls it, what it calls, what data flows through it</action>
    <rationale>A guess at the cause becomes a patch at the wrong layer. Reading is faster than re-debugging. Never modify code based on a guess about what it does.</rationale>
  </task>
  <task priority="2">
    <action>Reproduce the issue in an isolated environment</action>
    <rationale>Controlled reproduction ensures accurate diagnosis without affecting production</rationale>
  </task>
  <task priority="3">
    <action>Classify issue severity (Critical/High/Medium/Low)</action>
    <rationale>Proper classification ensures appropriate resource allocation and response time</rationale>
  </task>
  <task priority="4">
    <action>Analyze blast radius and affected systems</action>
    <rationale>Understanding impact scope guides containment and communication strategies</rationale>
  </task>
  <task priority="5">
    <action>Design debug strategy with appropriate wave count</action>
    <rationale>Tailored approaches ensure efficient resolution based on issue complexity</rationale>
  </task>
</critical_tasks>

<wave_planning_guidelines>
  <issue_type severity="Critical/Security">
    <waves>3+ waves</waves>
    <approach>Deep analysis, comprehensive fix, extensive validation, security audit</approach>
  </issue_type>
  <issue_type severity="Performance/Integration">
    <waves>2-3 waves</waves>
    <approach>Thorough diagnosis, targeted fix, performance verification</approach>
  </issue_type>
  <issue_type severity="UI/Minor">
    <waves>1-2 waves</waves>
    <approach>Quick fix, basic validation, user experience verification</approach>
  </issue_type>
</wave_planning_guidelines>

<required_outputs>
  <output>Issue classification with severity justification</output>
  <output>Detailed reproduction steps and environment details</output>
  <output>Impact analysis including affected users and systems</output>
  <output>Debug strategy document with planned wave activities</output>
</required_outputs>

</wave_0>

<dynamic_waves> Targeted Debugging Waves (Wave 1 to Wave N)

<context>
  Each debugging wave focuses on specific aspects of the issue, building upon previous findings. Teams adapt their approach based on the issue type while maintaining consistent quality standards.
</context>

<consistent_team_structure>
  <role name="Debug Engineer">Implements technical solutions and conducts analysis</role>
  <role name="Domain Expert">Provides specialized knowledge for the affected area</role>
  <role name="Test Engineer">Creates and executes comprehensive test scenarios</role>
  <role name="Record Keeper">Maintains detailed documentation of all activities</role>
</consistent_team_structure>

<debug_approaches>
  <approach type="Security Issues">
    <activities>
      - Conduct vulnerability analysis using security scanning tools
      - Develop exploit prevention mechanisms
      - Perform penetration testing on proposed fixes
      - Implement security hardening measures
    </activities>
    <focus>Ensure complete vulnerability remediation while maintaining system functionality</focus>
  </approach>
  
  <approach type="Performance Bugs">
    <activities>
      - Execute comprehensive profiling across system components
      - Identify and analyze performance bottlenecks
      - Implement optimization strategies
      - Validate improvements through benchmarking
    </activities>
    <focus>Achieve measurable performance improvements without sacrificing reliability</focus>
  </approach>
  
  <approach type="Integration Failures">
    <activities>
      - Perform API contract validation
      - Trace data flow through integrated systems
      - Test edge cases in integration points
      - Implement robust error handling
    </activities>
    <focus>Establish reliable communication between system components</focus>
  </approach>
  
  <approach type="Logic Errors">
    <activities>
      - Analyze state transitions and data transformations
      - Test boundary conditions and edge cases
      - Verify algorithm correctness
      - Implement comprehensive input validation
    </activities>
    <focus>Ensure logical correctness across all execution paths</focus>
  </approach>
  
  <approach type="UI/UX Issues">
    <activities>
      - Conduct cross-browser compatibility testing
      - Verify accessibility standards compliance
      - Test responsive design across devices
      - Validate user interaction flows
    </activities>
    <focus>Deliver consistent, accessible user experience across platforms</focus>
  </approach>
</debug_approaches>

<wave_deliverables>
  <deliverable>Root cause analysis with supporting evidence and timeline</deliverable>
  <deliverable>Implemented fix with clean, documented code</deliverable>
  <deliverable>Comprehensive regression test suite</deliverable>
  <deliverable>Performance impact measurement report</deliverable>
  <deliverable>Security assessment of all changes</deliverable>
</wave_deliverables>

</dynamic_waves>

<final_wave> Validation & System Hardening

<context>
  The final wave ensures that fixes are production-ready and the system is more robust than before. This comprehensive validation prevents regression and establishes safeguards against similar issues.
</context>

<team_composition>
  <role name="QA Lead">Oversees comprehensive testing and quality assurance</role>
  <role name="Security Auditor">Performs final security validation and compliance checks</role>
  <role name="Performance Engineer">Verifies system performance meets requirements</role>
  <role name="Record Keeper">Compiles final documentation and lessons learned</role>
</team_composition>

<validation_checklist>
  <step>Execute full regression test suite across all affected components</step>
  <step>Perform security scanning with multiple tools and methodologies</step>
  <step>Conduct performance benchmarking against baseline metrics</step>
  <step>Verify all edge cases and boundary conditions</step>
  <step>Test rollback procedures to ensure safe deployment</step>
  <step>Validate monitoring and alerting for the fixed issue</step>
</validation_checklist>

<final_outputs>
  <output name="DEBUG_REPORT.md">
    <content>Complete issue lifecycle documentation</content>
    <includes>Timeline, root cause, fix details, validation results</includes>
  </output>
  <output name="FIX_VALIDATION.md">
    <content>Comprehensive test results and metrics</content>
    <includes>Test coverage, performance benchmarks, security scan results</includes>
  </output>
  <output name="Updated Test Suites">
    <content>Enhanced tests preventing regression</content>
    <includes>Unit tests, integration tests, edge case coverage</includes>
  </output>
  <output name="Deployment Package">
    <content>Production-ready code with safety mechanisms</content>
    <includes>Fixed code, rollback plan, deployment instructions</includes>
  </output>
</final_outputs>

</final_wave> </wave_structure>

<debugging_principles> Always identify and address the fundamental cause, not just visible symptoms Fixing symptoms leads to recurring issues and technical debt accumulation

Test every fix in isolation before integration testing Isolated testing ensures the fix works correctly without environmental dependencies Document every finding, decision, and action taken during debugging Detailed documentation accelerates future debugging and knowledge sharing Capture and preserve system state before making any changes State preservation enables accurate analysis and safe rollback if needed Thoroughly analyze potential side effects of every fix Understanding side effects prevents introducing new bugs while fixing existing ones Implement permanent, well-tested solutions suitable for production Temporary workarounds create technical debt and future maintenance burden

<success_metrics> Original issue cannot be reproduced in any environment Multiple reproduction attempts across different scenarios

All related test cases pass consistently Automated test suite execution with 100% pass rate System performance remains at or above baseline levels Benchmarking results compared to pre-issue metrics Security stance maintained or enhanced Security audit results and vulnerability scan reports Clear documentation enables team learning Documentation review and team knowledge assessment

<key_deliverables> <deliverable_summary> Root cause analysis with supporting evidence and timeline Production-ready fix with comprehensive test coverage Prevention recommendations for similar issues Knowledge base updates for institutional learning Post-mortem analysis for critical issues </deliverable_summary> </key_deliverables>

<mode_specific_guidelines> Focus debugging efforts on understanding the complete problem context Before fixing a memory leak, analyze memory allocation patterns across the application

Implement monitoring and alerting for the specific issue being fixed Add performance metrics collection around the optimized code path Create regression tests that specifically target the bug scenario Write tests that reproduce the exact conditions that triggered the bug Share debugging insights with the broader team Conduct a lunch-and-learn session about the debugging techniques used

---

Standards (every wave must adhere)

Shadow Clone's canonical engineering standards live in ~/.claude/sc/protocols/ (deployed by bridge/install.sh). Every deliverable produced in this mode is judged against them. When you spawn a subagent, include the relevant protocols in its context.

Core (always apply):

• Functional Programming & Purity Protocol.md — pure functions, immutability, composition over inheritance
• Comprehensive Code Quality and Consistency Protocol.md — naming, structure, no dead code, no monoliths
• SECURITY_CHECKLIST.md — security-first per AGENTS.md Rule 8
• Error Handling & Resilience Protocol.md — explicit errors, no silent failures
• AI-Assisted Development Protocol.md — verification rigor on AI-generated work

Additional emphasis for this mode:

• Testing & Quality Assurance Protocol.md — reproduce the bug as a test before fixing

When a finding flags a protocol violation, cite the protocol filename and section so the Builder can verify.

---

Subagents & wave coordination

Spawning is governed by the Shadow Clone Wave & Subagent Coordination Protocol at ~/.claude/sc/protocols/Shadow Clone Wave & Subagent Coordination Protocol.md. Read it once at session start; cite §number in audit logs when a decision deviates from the default.

This mode's defaults

• Wave count: declared in <wave_structure> above. Hard ceiling at 5 waves.
• Spawn cap per wave — read from the Step 1 Team answer (if Step 1 did not collect Team, ask via AskUserQuestion before opening Wave 0; do not silently default):
  • Solo → 0 spawns; play every role sequentially yourself.
  • 2-3 → up to 2 specialist clones in parallel; you play the Record Keeper.
  • 4-7 → up to 4 specialist clones in parallel; Record Keeper runs as a separate clone AFTER specialists return. Per-wave concurrent peak is 4 (under the §1 hard cap of 5).
  • 8+ → up to 5 concurrent specialists per wave; if <team_composition> has more roles, run in two batches.
• Always-present role: Record Keeper. Never merged, never dropped. Authors the wave's deliverable.

Procedure (lives in the Protocol)

Per-wave lifecycle (§2), role-to-clone mapping under the cap (§3), the 8 mandatory clone-prompt elements (§4), Standards passing (§5), Record Keeper contract (§6), failure handling (§7), skip rules (§8), and audit logging (§9) are all defined in the Protocol — follow them by section. Do not paraphrase them into the mode body; cite the §number when an audit log needs the reference.

Closing each wave

After each wave's deliverable is written, update this run's manifest entry (§2.5): bump waves.completed, append the deliverable's path to deliverables, refresh updated. On the final wave-close, set status to complete. Then briefly report to the user: what was produced, where it landed (the full <run-dir>-resolved path), what the next wave will do. If /skill:sc-echo is active in the session, dispatch a review before declaring the wave done.

---

Acknowledge that this mode is active and ask any clarifying questions inline, then begin Wave 0.