starwave:smolspec

What this skill does

# Small Spec (Smolspec) - Lightweight Specification for Minor Changes

Create a lightweight specification for small changes that don't warrant the full spec workflow. This command combines research, planning, and task creation into a streamlined process.

## Scope Assessment

**Complexity Estimation:**
- The model MUST first estimate implementation complexity before proceeding
- Estimate lines of code to be added/modified (target: <80 LOC for smolspec)
- Count affected files and components (target: 1-3 files)
- Assess if this fits micro-plan criteria: single component, minimal dependencies
- The model MUST check whether an existing smolspec or full spec already covers the requested functionality

**Initial Research:**
- The model MUST explore the codebase to identify affected areas
- Identify existing patterns that can be leveraged
- Document dependencies and integration points
- Check for related features or ongoing work
- The model MUST capture a concise summary of affected files, dependencies, and unknowns before moving forward

**Assessment Questions:**
The model MUST answer these before proceeding:
- Is this truly a small, isolated change?
- Can this be implemented incrementally without breaking existing functionality?
- Are the requirements clear enough to proceed without extensive clarification?
- Does the codebase have established patterns for this type of change?

**Escalation Criteria:**
If the change meets ANY of these criteria, the model MUST recommend using the full spec workflow instead:
- Affects multiple subsystems or architectural boundaries
- Requires breaking changes or significant API modifications
- Impacts backward compatibility
- Involves complex business logic or multiple user workflows
- Requires coordination across multiple components
- Has significant security, performance, or reliability implications
- Estimated implementation >80 lines of code or >3 files
- Requirements are ambiguous or need extensive clarification
- The user explicitly requests a full spec
- If uncertain between smolspec vs full spec, the model SHOULD default to recommending the full spec workflow

If escalation is needed, the model MUST:
1. Explain why the full spec workflow is more appropriate
2. Highlight specific complexity factors discovered during research
3. Provide the complexity metrics (LOC estimate, file count, dependencies)
4. Recommend starting with `/starwave:requirements` skill instead
5. STOP execution of smolspec workflow

## Feature Naming

- The model MUST propose a {feature_name} based on: (1) user's explicit preference, (2) current branch name if not a default branch, (3) derived from the prompt
- The model MUST allow the user to override the proposal
- Feature names should be concise and descriptive (e.g., "add-logging", "fix-validation")
- The model MUST sanitize feature names into filesystem-safe kebab-case slugs and ensure they do not collide with existing specs
- The model MUST wait for user approval of the feature name

## Lightweight Documentation

For changes that are appropriate for smolspec, the model MUST create documentation in two files:

**File Structure:**
- Create `specs/{feature_name}/smolspec.md` for requirements and design
- Create `specs/{feature_name}/tasks.md` for implementation tasks (compatible with next-task skill)
- Create `specs/{feature_name}/decision_log.md` if any decisions need to be documented

**Document Formats:**

The smolspec.md file MUST contain these sections:

```markdown
# {Feature Name}

## Overview
Brief description of what this change does and why it's needed (2-4 sentences).

## Requirements
Simple list of what needs to be accomplished using specification language:
- The system MUST {core requirement 1}
- The system SHOULD {recommended approach}
- The system MAY {optional enhancement}

Note: Use MUST for non-negotiable requirements, SHOULD for strong recommendations, MAY for optional features.

## Implementation Approach
Brief description of how this will be implemented:
- Key files to modify (with paths)
- Approach or pattern to use (reference existing similar implementations if available)
- Any important technical considerations
- Dependencies (existing code/libraries this relies on)
- Out of Scope (what will NOT be changed)

## Risks and Assumptions
Brief list of technical risks and key assumptions:
- Risk: {potential problem} | Mitigation: {how to address}
- Assumption: {what we're assuming is true}
- Prerequisite: {what must exist/work before this can be implemented}
```

The tasks.md file MUST follow the standard task format to be compatible with the next-task skill:
- Numbered checkbox list with maximum two levels of hierarchy
- May optionally group tasks into 1-2 phases if helpful for organization
- Total task count SHOULD be 4-10 tasks (small changes shouldn't need more)
- Each task must reference the smolspec.md file
- Tasks build incrementally on previous steps

**Task Description Guidelines:**
- Tasks MUST describe WHAT outcome is needed, not HOW to implement
- Tasks SHOULD be verifiable with clear success criteria
- Tasks MUST avoid prescriptive implementation details
- Bad example: "Add validateEmail() function to utils.go"
- Good example: "Email validation prevents invalid addresses from being submitted"
- Each task SHOULD include verification steps (testing distributed throughout, not consolidated at end)
- Tasks MUST represent meaningful units of work. Do NOT fragment a single coherent change into separate tasks for setup, implementation, and wiring (e.g., "create file", "add import", "implement function", "connect it up"). Combine trivial substeps into one task.
- Tasks MUST NOT implement or prepare for anything listed in the smolspec's Out of Scope section.

**Documentation Constraints:**
- Keep smolspec.md concise (typically under 100 lines total)
- Requirements MUST use specification language (MUST/SHOULD/MAY)
- Implementation approach MUST reference specific file paths and existing patterns
- Risks and Assumptions section MUST identify at least one risk or assumption
- Tasks MUST be outcome-focused and verifiable
- Testing MUST be distributed across tasks, not consolidated into final task
- All tasks MUST involve writing, modifying, or testing code (no deployment, user acceptance testing, etc.)

## Workflow Process

**1. Research Phase:**
- Conduct initial research to understand the codebase and change scope
- Identify affected files and components
- Check for existing patterns to follow
- Assess complexity and determine if full spec is needed
- Share the research summary (scope, risks, references) with the user before planning

**2. Planning Phase (if not escalated):**
- Propose feature name and get approval
- Create initial smolspec.md with all required sections (Overview, Requirements, Implementation Approach, Risks and Assumptions)
- Ask clarifying questions if needed (use AskUserQuestion tool)
- Keep documentation minimal but complete
- Ensure smolspec is self-contained (assume fresh AI session will execute without conversation history)
- Use the design-critic skill to review the smolspec.md document
- Incorporate the design-critic's feedback and recommendations into the smolspec.md
- Update the document based on valid critiques before presenting to user
- Capture any noteworthy decisions or trade-offs identified during critique inside `specs/{feature_name}/decision_log.md`

**3. Self-Review Phase:**
Before presenting to user, the model MUST verify:
- [ ] Requirements use specification language (MUST/SHOULD/MAY) and are testable
- [ ] Requirements describe observable behavior, not implementation mechanism (no "MUST use library X", "MUST be implemented as a service")
- [ ] Implementation approach references specific files with paths
- [ ] Implementation approach references existing patterns or similar code
- [ ] At least one risk or assumption is documented with mitigation/validation plan
- [ ] Dependencies and prerequisites are clearly stated
- [ ] Out of scope