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)