troubleshooting_skill

Overview

This skill diagnoses and resolves common problems during spec-driven development and implementation. It provides clear actions for gaps between spec and reality, blocked tasks, unclear requirements, test and performance issues, integration failures, and scope creep. Use it to restore progress quickly and keep work aligned with requirements.

How this skill works

The skill inspects symptoms, assesses impact, and recommends concrete resolution patterns: update the spec, redesign, reorder or split tasks, mock dependencies, refactor, optimize performance, or add integration tests. It also prescribes prevention steps and debugging techniques to reduce recurrence. Each recommendation includes immediate actions, follow-up validation, and documentation practices to keep stakeholders aligned.

When to use it

• When implementation diverges from the spec or assumptions fail
• When tasks are blocked by dependencies or circular work
• When requirements or edge cases are unclear during coding
• When tests are flaky, slow, or hard to write
• When performance or integration problems appear
• When scope creep threatens timelines or quality

Best practices

• Document gaps and impacts immediately; stop work if core assumptions break
• Prototype or spike risky integrations during design to validate assumptions
• Map and order dependencies explicitly; split tasks to unblock progress
• Design for testability: interfaces, fixtures, and test strategy in the spec
• Measure before optimizing: profile, fix the biggest bottleneck, then re-measure
• Update the spec whenever assumptions, requirements, or designs change and record rationale

Example use cases

• API response shape differs from spec: create a minimal stub and update spec or redesign if core assumption broken
• Blocked task needs later feature: split task and implement non-blocked parts; queue dependent work
• Flaky integration tests: isolate external calls with mocks, add integration tests, and stabilize environments
• Performance regression in production: profile, add indexes or caching, measure improvement, and add performance tests
• Unclear requirement found while implementing: propose a solution with rationale, get stakeholder sign-off, and update acceptance criteria