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

New Issue

Claude · 2026-06-28T17:11:33Z

Claude commented

2026-06-28 17:11:33 +00:00

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
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
break-into-issues: independently shippable issue bodies; each issue may include a Design notes section for non-trivial implementation specifics; 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

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 and write-prd
github/spec-kit and Fission-AI/OpenSpec — PRD and issue spec standards

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
grill-me correctly calls write-adr by skill name
write-prd includes inline self-checks that reject PRDs containing implementation approach or technical design
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 → source review → conflict check → synthesis grill → co-write iteratively
Trigger description for each skill tested against explicit, implicit, and negative queries before body written
eval.yaml for each skill contains all 5 required test types
Body ≤500 lines for each skill
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)

**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 - `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 - `break-into-issues`: independently shippable issue bodies; each issue may include a Design notes section for non-trivial implementation specifics; 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 **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` and `write-prd` - `github/spec-kit` and `Fission-AI/OpenSpec` — PRD and issue spec standards ## 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 - [ ] `grill-me` correctly calls `write-adr` by skill name - [ ] `write-prd` includes inline self-checks that reject PRDs containing implementation approach or technical design - [ ] `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 → source review → conflict check → synthesis grill → co-write iteratively - [ ] Trigger description for each skill tested against explicit, implicit, and negative queries before body written - [ ] eval.yaml for each skill contains all 5 required test types - [ ] Body ≤500 lines for each skill - [ ] `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)

Claude added this to the Legacy / Triage milestone 2026-06-28 17:11:33 +00:00

Claude added the Kind/Feature

Priority

Medium

3

labels 2026-06-28 17:11:33 +00:00

Claude referenced this issue

2026-06-28 17:14:45 +00:00

refactor: align repo with marketplace/plugin model — migrate docs and issues to Gitea, rewrite specs, clean up stale artifacts #15

Claude modified the milestone from Legacy / Triage to Skills & Agents

2026-06-28 19:26:47 +00:00

Sign in to join this conversation.