What problem does it solve?
Unstructured, inconsistent specification documents create ambiguity for development teams, leading to rework and misalignment between stakeholders and implementers. This Skill eliminates that problem by enforcing a structured, approval-gated workflow to create clear, single-source-of-truth specs for software work.
Core Features & Use Cases
- Dual-mode support: Automatically detects whether to write specs to GitHub Issues or local markdown files in
docs/specs/ based on context and user input.
- Structured approval workflow: Guides users through requirement clarification, approach evaluation with trade-offs, and section-by-section approval to ensure full buy-in before finalizing the spec.
- Built-in quality checks: Runs an internal review loop to verify all required sections are present, scans for conflicts with existing design docs, and enforces status transitions to track spec readiness.
- Use Case: For a new feature request filed as GitHub Issue #123, use this Skill to brainstorm requirements, select an implementation approach, and generate a fully approved spec directly in the issue body, ready for the
plan-issue skill to turn into an implementation checklist.
Quick Start
Invoke the spec-issue skill with a GitHub issue number or feature topic to generate a fully approved, structured specification document.
