home / skills / shotaiuchi / dotclaude / wf2-spec

wf2-spec skill

safe

This skill creates or updates a Spec document by extracting kickoff details, analyzing codebase, and ensuring consistency with existing specs.

npx playbooks add skill shotaiuchi/dotclaude --skill wf2-spec

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

1.8 KB

---
name: wf2-spec
description: 仕様書（Spec）ドキュメントを作成
argument-hint: "[update | validate]"
context: fork
agent: general-purpose
---

**Always respond in Japanese.**

# /wf2-spec

Create or update the Specification (Spec) document.

## Usage

```
/wf2-spec [subcommand]
```

## Subcommands

- `(none)`: Create new Spec
- `update`: Update existing Spec
- `validate`: Check consistency with Kickoff

## Processing

### 1. Check Prerequisites

Get active work. Require `01_KICKOFF.md` exists.

### 2. Load and Analyze Kickoff

Extract: Goal, Success Criteria, Constraints, Dependencies.

### 3. Investigate Codebase

Use Glob/Grep for file discovery. Use Task tool with Explore agent for complex analysis.

Checklist: identify affected files, check existing patterns, check related tests, check existing specs in `docs/spec/`.

### 4. Create Spec

Load template `~/.claude/templates/02_SPEC.md`. Fill with investigation results and Kickoff content.

### 5. Consistency Check

1. **With Kickoff**: Goal reflected, Success Criteria achievable, Constraints considered
2. **With existing specs**: No contradictions with `docs/spec/`, API compatibility
3. **Test strategy**: Tests exist to verify Success Criteria

If issues found: list warnings, ask user to address or document reasoning in Notes.

### 6. Update state.json

Set `current: "wf2-spec"`, `next: "wf3-plan"`.

### 7. Commit

`docs(wf): create spec <work-id>` (or `update spec`).

### 8. Completion Message

Show file path, affected components with severity, next step (`/wf3-plan`).

## validate Subcommand

Check Kickoff↔Spec consistency. Display OK/warning/missing for each criterion.

## Notes

- Do not change Kickoff content arbitrarily
- Warn on contradictions with existing specs
- Suggest Kickoff revision if technically infeasible

Overview

This skill creates or updates a Specification (Spec) document from an active work kickoff and the codebase. It automates investigation, fills a Spec template with findings, checks consistency with the kickoff and existing specs, updates workflow state, and produces a clear next-step message. It supports creating new Specs, updating existing ones, and validating alignment between Kickoff and Spec.

How this skill works

The skill first verifies prerequisites and loads the active kickoff to extract Goal, Success Criteria, Constraints, and Dependencies. It inspects the codebase to detect affected files, patterns, tests, and existing spec fragments, then populates a Spec template with the combined results. A consistency pass compares Kickoff vs Spec, checks for contradictions with other specs and test coverage, records warnings, updates workflow state, and stages a commit message.

When to use it

When starting a new work item and a formal Spec is required
When an existing Spec needs updates based on code or requirement changes
Before planning to ensure goals and success criteria are feasible
To validate alignment between the Kickoff document and the current Spec
When documenting affected files and test strategy for traceability

Best practices

Ensure the active Kickoff document exists and is complete before running
Keep Constraints and Dependencies explicit in the Kickoff to reduce ambiguity
Run code discovery early and use the Explore agent for complex repo analysis
Document any intentional deviations from the Kickoff in the Spec Notes
Address high-severity contradictions before proceeding to planning

Example use cases

Generate a new Spec from an approved Kickoff to start technical planning
Update a Spec after refactoring to reflect changed file ownership and interfaces
Validate that the Spec still meets Kickoff Success Criteria before a release
Identify missing tests that are required to verify Success Criteria
List affected components and severity to inform stakeholders and next steps

FAQ

What prerequisites are required?

An active work context and an existing kickoff document are required before creating or updating a Spec.

What happens if the Spec contradicts the Kickoff?

The skill lists warnings, highlights contradictions, and recommends either updating the Kickoff or documenting the technical rationale in the Spec Notes.