to-spec

Files (1)

• SKILL.md

SKILL.md (first lines)

# To Spec

把 PRD、Plan 或 conversation context 转成 AI 可执行的功能和技术规格。输出默认写入 `docs/features/<feature>/SPEC.md`。

## Workflow

1. **Load repo workflow**
   - Read the repo's actual agent adapter if present, such as `AGENTS.md`, `CLAUDE.md`, `.cursor/rules/`, or `.github/copilot-instructions.md`
   - Read `docs/agents/document-system.md` and `docs/agents/domain.md` if they exist
   - Read `CONTEXT.md` and relevant `docs/adr/`
   - If source material comes from BMad or `_bmad-output/`, read `docs/BMAD_INTEGRATION.md` and `docs/LEVEL3_BMAD_WORKFLOW.md`

2. **Find source material**
   - Prefer `docs/features/<feature>/PRD.md`
   - Also read `docs/features/<feature>/PLAN.md` if present
   - If BMad was used, read relevant BMad PRD, architecture, epics/stories, readiness, review, or story files as source material
   - If no PRD exists, use conversation context and mark assumptions explicitly

3. **Explore code only as needed**
   - Inspect existing API, models, tests, and module boundaries related to the feature
   - Use project vocabulary from `CONTEXT.md`
   - Respect ADR constraints; flag conflicts instead of silently overriding them

4. **Draft the Spec**
   - Describe external behavior, not internal implementation steps
   - Include functional scenarios, state transitions, business rules, error scenarios, data model, API contract, validation rules, and verification commands
   - Do not invent product scope that is absent from the PRD; put uncertain scope under `Open Questions`
   - Promote only stable BMad conclusions into `SPEC.md`; BMad task ordering, story execution notes, and transient review notes stay in `_bmad-output/` or control issues
   - If BMad output conflicts with existing `docs/`, stop and surface the conflict; update `docs/` only after the chosen conclusion is clear

5. **Write or update**
   - Create `docs/features/<feature>/SPEC.md`
   - If updating an existing Spec, preserve still-valid content and change only affected sections
   - Ensure `Parent PRD` points to `docs/features/<feature>/PRD.md`

6. **Finish with next step**
   - If sequencing is still unclear or the work spans phases/features, suggest `/to-plan`
   - If the Spec is implementation-ready and AI-native issues own execution, suggest `/to-issues`
   - If BMad story cycle owns execution, suggest `bmad-sprint-planning`; use `/to-issues` only for blocker, HITL, risk, debt, review follow-up, or documentation-fix control issues
   - If terminology is unresolved, suggest `/grill-with-docs`
   - If a durable technical trade-off appears, suggest an ADR

## Required Spec Shape

```markdown
# Spec: <Feature Name>

> Parent PRD: docs/features/<feature>/PRD.md
> Related ADR: <links or None>

## Overview

## Functional Specification

### User Scenarios

### State Transitions

### Business Rules

### Error Scenarios

## Technical Specification

### Data Model

### API Contract

### Validation Rules

## Verification

### Automated Verification Commands

| Command | Expected Result | Failure Handling |
| ------- | --------------- | ---------------- |
| `<build>` | <expected> | <what to fix> |
| `<test>` | <expected> | <what to fix> |

### Manual QA Steps

### Known Non-Testable Acceptance Criteria

## Open Questions
```

## Quality Bar

- Every user-visible behavior in the PRD has a corresponding Spec rule or scenario.
- Every API/data/state rule has an observable reason from PRD, Context, or ADR.
- Verification commands are concrete commands an agent can run.
- Spec does not mention exact source file paths unless they are part of a public contract.
- Ambiguity is explicit; do not hide unknowns in vague wording.

From pop1414/ai-native-doc-system, MIT.

More from pop1414/ai-native-doc-system