playbooks

home / skills / shotaiuchi / dotclaude / ghwf2-spec

ghwf2-spec skill

/dotclaude/skills/ghwf2-spec

This skill helps you generate a comprehensive specification document from GitHub issues and kickoff notes, automating structure and templates.

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

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

Files (1)
SKILL.md
1.7 KB
---
name: ghwf2-spec
description: 仕様書ドキュメントを作成
argument-hint: "[update | revise]"
context: fork
agent: general-purpose
---

**Always respond in Japanese. Write all workflow documents (*.md) in Japanese.**

# /ghwf2-spec

GitHub Issue とキックオフドキュメントから仕様書を作成する。

## Usage

```
/ghwf2-spec           # 新規作成
/ghwf2-spec update    # 対話形式で更新
/ghwf2-spec revise    # フィードバックに基づいて更新
```

## Prerequisites

- `ghwf1-kickoff` 完了済み
- `01_KICKOFF.md` が存在

## Processing

### 1. Load Context

- Read `state.json` for active work
- Read `01_KICKOFF.md`
- Fetch Issue with comments:
  ```bash
  gh issue view <issue> --json body,comments
  ```
  - Include comments as additional requirements

### 2. Create 02_SPEC.md

- Template: `~/.claude/templates/02_SPEC.md`
- Sections:
  - Functional Requirements
  - Non-functional Requirements
  - Data Model
  - API/Interface Design
  - Edge Cases

### 3. Commit & Push

**Execute immediately without confirmation:**

```bash
git add docs/wf/<work-id>/02_SPEC.md
git commit -m "docs(wf): create spec <work-id>"
git push
```

### 4. Update PR Body

チェックリスト更新:
```markdown
- [x] ghwf1-kickoff
- [x] ghwf2-spec  ← チェック
- [ ] ghwf3-plan
...
```

### 5. Update Labels

```bash
gh issue edit <issue> --add-label "ghwf:step-2"
```

### 6. Update State

```json
{
  "current": "ghwf2-spec",
  "next": "ghwf3-plan",
  "last_execution": "<ISO8601>"
}
```

## Revise Processing

1. Check for updates since last execution
2. Incorporate feedback into spec
3. Append revision entry
4. Commit: `docs(wf): revise spec <work-id>`

Overview

This skill automates creation and revision of a formal specification document (02_SPEC.md) from a GitHub Issue and kickoff document. It reads project context, merges issue comments as requirements, writes the spec using a template, commits the file, updates the PR checklist and issue labels, and advances workflow state. It supports interactive updates and revision flows triggered by feedback.

How this skill works

The skill loads active work context from state.json and the existing 01_KICKOFF.md, then fetches the target GitHub Issue body and comments to capture requirements. It fills a predefined template (~/.claude/templates/02_SPEC.md) with Functional and Non-functional Requirements, Data Model, API/Interface Design, and Edge Cases. Finally it commits and pushes the new spec, updates the pull request checklist, adjusts issue labels, and writes the next workflow state.

When to use it

  • After completing kickoff (ghwf1-kickoff) and confirming 01_KICKOFF.md is present
  • When an Issue contains requirements and discussion that must be formalized into a spec
  • When you need a reproducible, committed spec file in docs/wf/<work-id>/02_SPEC.md
  • When feedback arrives and the spec must be revised and versioned

Best practices

  • Ensure 01_KICKOFF.md and state.json are up to date before running
  • Keep issue comments focused; the skill treats comments as additional requirements
  • Review generated Functional and Non-functional sections for domain nuance before wide distribution
  • Use the interactive update mode to refine scope before final commit
  • Append clear revision notes when incorporating feedback to preserve traceability

Example use cases

  • Convert a feature request Issue with stakeholder comments into a formal spec ready for planning
  • Generate an initial API design and data model from kickoff artifacts to hand to engineering
  • Apply reviewer feedback to an existing spec and publish a committed revision
  • Automate checklist progression and labeling so the next workflow step (ghwf3-plan) is unblocked

FAQ

What files must exist before running this skill?

You must have completed ghwf1-kickoff and have 01_KICKOFF.md in the work directory; state.json must reflect the active work.

Does the skill require confirmation before pushing commits?

No. By design it stages, commits, and pushes the spec immediately to keep workflow automated.