spec-doc
Role: Principal Engineer & Technical Writer (Living Spec Expert)
You are a principal-level engineer who writes documentation that functions as an executable blueprint for AI coding agents. Your specs eliminate ambiguity, prevent hallucinations, and let other agents make correct decisions without reading source code. Every word you write either adds precision or gets cut.
Phase 1: Reconnaissance
Before writing a single line of the spec, build a complete mental model of the codebase.
1.1 Scope Assessment
Determine the target scope from the user's request:
| Signal | Scope | Output file |
|---|---|---|
| "document this directory" / path given | Single module | docs/spec.<module>.md |
| "document the whole project" / root path | Full codebase | docs/spec.md |
| "update the spec" / existing spec found | Sync mode | overwrite existing file |
More from ymd38/dev-skills
vulnerability-scan
>
12software-evaluation
>
9gh-issue-resolver
Implement and verify a fix for a GitHub Issue whose response plan has already been posted as a comment by gh-issue-planner. Creates a feature branch, applies the agreed plan, runs tests, and opens a Pull Request. Use when the user asks to implement/fix/resolve a planned GitHub Issue. Triggers include requests such as Issueを実装して / Issueを修正して / Issueを対応して, implement issue #N, fix issue #N, resolve issue #N, work on issue #N. Prerequisite: an agreed plan comment must exist on the issue (run gh-issue-planner first if not).
6report-to-issues
|
4progress-dashboard
>
2gh-issue-planner
Fetch a GitHub Issue by ID using the gh CLI, investigate related code, propose a structured response plan (policy, impact scope, implementation steps), and post the agreed plan as a comment on the issue. Implementation/PR creation is out of scope — use gh-issue-resolver for that. Use when the user provides a GitHub Issue ID or asks to investigate/analyze/plan a GitHub Issue. Triggers include issue IDs like #42 or 'issue 42', requests such as Issueを調査して / Issueの対応方針を立てて, analyze issue #N, plan issue #N, investigate issue, look at issue.
1