holocron/docs/issues/0020-design-skills.md

# 0020 — Design skills: grill-lean, grill-me, write-prd, architecture-review, break-into-issues, prototype

**Type:** HITL
**Parent PRD:** `docs/prd/chunk-3-skills-library.md`

## What to build

The 6 design phase skills. Four are refactors of existing Pocock placeholders; two are new. All are authored using `write-skill` (0018) and evaluated using `write-eval` (0017).

**Skills, origins, and trigger descriptions:**

| Flat name | Origin | Trigger description |
|---|---|---|
| `grill-lean` | Refactored from Pocock `grill-me` | Lightweight: quick interrogation without docs integration |
| `grill-me` | Refactored from `grill-with-docs`; calls `write-adr` | Grill me on this idea, help me think through X before building, interrogate my plan |
| `write-prd` | Refactored from Pocock `to-prd` | Write a PRD, document requirements, write the product spec |
| `architecture-review` | New | Review architecture, assess system design, evaluate technical approach |
| `break-into-issues` | Refactored from Pocock `to-issues` | Break this into issues, decompose this spec into tasks, what issues do I need for this |
| `prototype` | Preserved; frontmatter + standard added | Prototype this idea, explore this with a spike |

**Key constraints per skill:**
- `grill-me`: must refuse to produce code until all decisions are explicit; calls `write-adr` when a decision crystallises; integrates domain model from CONTEXT.md; output is a structured decision summary
- `grill-lean`: lightweight secondary path — quick interrogation without domain model integration or ADR writing
- `write-prd`: contains why + what only — problem statement, goals, explicit non-goals, functional requirements at feature level, success criteria. Never contains HOW: HOW is deferred to `architecture-review` (technical approach options with tradeoffs) and/or issue design notes (per-issue implementation specifics). Inline self-checks in the skill reject PRDs that drift into implementation territory.
- `architecture-review`: the designated home for HOW at the workstream level — must present ≥2 technical approach options with tradeoffs; never recommends a single option without alternatives; optional step run after `write-prd` when the technical approach is non-obvious or carries meaningful risk
- `break-into-issues`: independently shippable issue bodies; each issue may include a Design notes section for non-trivial implementation specifics (issue-level HOW); proposes Gitea milestone groupings for PRDs producing >5 issues; does not post — outputs bodies for human review
- `prototype`: add frontmatter and authoring standard sections; preserve existing behavior; exploratory HOW artifacts (spikes, proofs of concept) that inform architecture-review or issue design notes

**Composition:** `grill-me` calls `write-adr` by name. `write-adr` must exist (0019) before `grill-me` is finalized.

## Implementation notes

Follow the per-skill workflow defined in `docs/notes/skill-implementation-workflow.md`.

**Known upstream sources to review for this category:**
- `mattpocock/skills` — original `grill-me`, `to-prd`, `to-issues`, `grill-with-docs` placeholders; review at current HEAD for improvements; record SHAs in `source:` for refactored skills
- `bmad-method/bmad-method` — BMAD design phase patterns; relevant for `break-into-issues` (issue embedding, independently completable slices) and `write-prd` (PRD scope discipline)
- `github/spec-kit` and `Fission-AI/OpenSpec` — PRD and issue spec standards; relevant for `write-prd` and `break-into-issues` constraint design

For new skills (`architecture-review`, `grill-lean`): search for prior art in the above repos and agentskills.io before writing from scratch; document adoption in `source:`.

## Acceptance criteria

- [ ] All 6 SKILL.md files exist at `.agents/skills/<skill-name>/SKILL.md`; `metadata.category: design`; authoring standard met
- [ ] Dead references removed from all refactored Pocock skills (`setup-matt-pocock-skills`, `AGENT-BRIEF.md`, `OUT-OF-SCOPE.md`)
- [ ] `grill-me` correctly calls `write-adr` by skill name
- [ ] `write-prd` includes inline self-checks that reject PRDs containing implementation approach, technical design, or EARS-level detail — and directs those to `architecture-review` or issue design notes
- [ ] `architecture-review` presents ≥2 options with tradeoffs in all outputs
- [ ] `source:` fields populated for all refactored skills (repo slug, commit SHA, files adopted, updated date)
- [ ] Each skill has a co-located eval at `.agents/evals/design/<skill-name>/eval.yaml` produced via `write-eval`
- [ ] `install.sh` deploys all 6 to `~/.agents/skills/`
- [ ] **HITL:** human runs behavioral test per skill; output meets constraints
- [ ] **HITL:** human reviews each SKILL.md and eval before committing
- [ ] Per-skill process followed for all 6 skills: source discovery (sub-agent) → source review with licence/security check (sub-agent) → conflict check against constitution + factory principles (sub-agent) → synthesis grill → co-write iteratively
- [ ] Trigger description for each skill tested against explicit, implicit, and negative queries before body written
- [ ] `when:` frontmatter field present in all SKILL.md files
- [ ] `source:` fields populated for all refactored Pocock skills; `references:` present if external citations used
- [ ] eval.yaml for each skill contains all 5 required test types
- [ ] Body ≤500 lines for each skill
- [ ] Conflict check run against constitution before synthesis grill; no unresolved HITL or data classification violations
- [ ] `docs/spec/overview.md` updated to reflect all 6 skills deployed

## Blocked by

- 0016 (grill defines per-skill workflow; `docs/notes/skill-implementation-workflow.md` must exist)
- 0017 (`write-eval` needed to produce evals)
- 0018 (`write-skill` used to author these skills)
- 0019 (`write-adr` must exist before `grill-me` can call it)