design: nothing in the 39-skill corpus produces a PRD #123

New Issue

Claude · 2026-08-31T08:06:42Z

Claude commented

2026-08-31 08:06:42 +00:00

Found during the #99 ADR-0020 retrofit and the follow-up audit pass on refactor/adr0020-skill-retrofit. A dangling route was fixed there; the underlying gap was left open on purpose, because closing it is a build-or-declare decision, not an edit.

What was found

bin/write-docs/SKILL.md routed PRD requests to to-prd — twice:

- User wants a PRD, decision doc, or architecture proposal → `to-prd` or `grill-me`
- Requested output is a PRD, decision doc, or architecture proposal → redirect to `to-prd`, `grill-me`, or `grill-with-docs`

to-prd does not exist anywhere in this repo and has not since the great refactoring — that milestone's own scope line says "delete stale bin skills (to-issues, to-prd)". Grepping the tree now, the name survives only in docs/research/, docs/notes/, and one kyberforge research example; no SKILL.md anywhere.

Commit 03abcff removed the dangling name. Both lines now route to grill-me / grill-with-docs.

Why that is a route repair, not a fix

Neither target emits a PRD.

grill-me is an interview loop: it interrogates a plan until shared understanding is reached. Its output is the conversation.
grill-with-docs is the same loop with documentation side effects — it updates CONTEXT.md inline as terms are sharpened, and offers an ADR when a decision crystallises.

So of the three things write-docs disclaims, two are genuinely covered — "decision doc" and "architecture proposal" are grill-with-docs' ADR authoring, and that is a real artifact with a real format (grill-with-docs's ADR-FORMAT.md). "PRD" is not covered by anything. write-docs now points a PRD request at a skill that will have a good conversation with the user and write an ADR.

That is more honest than pointing at a skill that does not exist, and it is still wrong.

Origin, and the shape the answer was going to take

docs/research/ai-coding-factory/ai-coding-factory-implementation-guidance.md:112 records the upstream pattern as worth adopting:

| /to-prd skill | Converts conversation into a structured PRD artifact | Adopt the forcing-function pattern: refuse to proceed until synthesis is complete |

and line 236 maps it onto a write-issue-spec skill:

write-issue-spec was specified in some detail (ai-coding-factory-skills-index.md:38 — EARS-format requirements, delta tags for brownfield, scale-adaptive depth, outputs a Gitea issue body for human review rather than posting it) and never built. docs/notes/factory-research-gaps-conflicts.md:64 already flags the seven factory meta-skills, this among them, as "not in the current roadmap at all".

The decision

Two acceptable outcomes, and doing nothing is not one of them because write-docs currently makes a routing promise the corpus cannot keep:

Build it. Most likely as write-issue-spec per the research, not as a literal to-prd — this repo's unit of pre-work is a Gitea issue with an EARS spec (ADR-0007, and the implementation guidance's "issue spec precedes code" rule at line 85), not a standalone PRD document. Then repoint write-docs.
State the gap. Reword write-docs' two lines to say a PRD has no owner here and stop implying a destination, and record why in the factory notes so it is not rediscovered a third time.

Worth noting that option 1 has a boundary question attached: a write-issue-spec that drafts an issue body sits next to triage, which already owns issue-workflow state, and next to gitea-issues, which owns the posting. That boundary needs drawing before the skill is written.

Files

plugins/bin/.apm/skills/write-docs/SKILL.md — "Do not use when" and "Failure handling"
docs/research/ai-coding-factory/ai-coding-factory-implementation-guidance.md:85,112,236
docs/research/ai-coding-factory/ai-coding-factory-skills-index.md:38
docs/notes/factory-research-gaps-conflicts.md:64

#99 — the retrofit during which this surfaced
#100 — the earlier round of boundary clauses routing to targets that do not exist (description-level; this one was in a body, which no gate covers — filed separately alongside this issue)

Found during the #99 ADR-0020 retrofit and the follow-up audit pass on `refactor/adr0020-skill-retrofit`. A dangling route was fixed there; the underlying gap was left open on purpose, because closing it is a build-or-declare decision, not an edit. ## What was found `bin/write-docs/SKILL.md` routed PRD requests to `to-prd` — twice: ``` - User wants a PRD, decision doc, or architecture proposal → `to-prd` or `grill-me` - Requested output is a PRD, decision doc, or architecture proposal → redirect to `to-prd`, `grill-me`, or `grill-with-docs` ``` `to-prd` does not exist anywhere in this repo and has not since the great refactoring — that milestone's own scope line says *"delete stale bin skills (to-issues, to-prd)"*. Grepping the tree now, the name survives only in `docs/research/`, `docs/notes/`, and one kyberforge research example; no `SKILL.md` anywhere. Commit `03abcff` removed the dangling name. Both lines now route to `grill-me` / `grill-with-docs`. ## Why that is a route repair, not a fix Neither target emits a PRD. - `grill-me` is an interview loop: it interrogates a plan until shared understanding is reached. Its output is the conversation. - `grill-with-docs` is the same loop with documentation side effects — it updates `CONTEXT.md` inline as terms are sharpened, and offers an ADR when a decision crystallises. So of the three things `write-docs` disclaims, two are genuinely covered — "decision doc" and "architecture proposal" are `grill-with-docs`' ADR authoring, and that is a real artifact with a real format (`grill-with-docs`'s `ADR-FORMAT.md`). "PRD" is not covered by anything. `write-docs` now points a PRD request at a skill that will have a good conversation with the user and write an ADR. That is more honest than pointing at a skill that does not exist, and it is still wrong. ## Origin, and the shape the answer was going to take `docs/research/ai-coding-factory/ai-coding-factory-implementation-guidance.md:112` records the upstream pattern as worth adopting: | `/to-prd` skill | Converts conversation into a structured PRD artifact | Adopt the forcing-function pattern: refuse to proceed until synthesis is complete | and line 236 maps it onto a `write-issue-spec` skill: | Pocock/skills | `to-prd/SKILL.md` | Pattern only — forcing-function approach | `.agents/skills/factory/write-issue-spec/SKILL.md` | `write-issue-spec` was specified in some detail (`ai-coding-factory-skills-index.md:38` — EARS-format requirements, delta tags for brownfield, scale-adaptive depth, outputs a Gitea issue body for human review rather than posting it) and never built. `docs/notes/factory-research-gaps-conflicts.md:64` already flags the seven factory meta-skills, this among them, as "not in the current roadmap at all". ## The decision Two acceptable outcomes, and doing nothing is not one of them because `write-docs` currently makes a routing promise the corpus cannot keep: 1. **Build it.** Most likely as `write-issue-spec` per the research, not as a literal `to-prd` — this repo's unit of pre-work is a Gitea issue with an EARS spec (ADR-0007, and the implementation guidance's "issue spec precedes code" rule at line 85), not a standalone PRD document. Then repoint `write-docs`. 2. **State the gap.** Reword `write-docs`' two lines to say a PRD has no owner here and stop implying a destination, and record why in the factory notes so it is not rediscovered a third time. Worth noting that option 1 has a boundary question attached: a `write-issue-spec` that drafts an issue body sits next to `triage`, which already owns issue-workflow state, and next to `gitea-issues`, which owns the posting. That boundary needs drawing before the skill is written. ## Files - `plugins/bin/.apm/skills/write-docs/SKILL.md` — "Do not use when" and "Failure handling" - `docs/research/ai-coding-factory/ai-coding-factory-implementation-guidance.md:85,112,236` - `docs/research/ai-coding-factory/ai-coding-factory-skills-index.md:38` - `docs/notes/factory-research-gaps-conflicts.md:64` ## Related - #99 — the retrofit during which this surfaced - #100 — the earlier round of boundary clauses routing to targets that do not exist (description-level; this one was in a body, which no gate covers — filed separately alongside this issue)

Claude added this to the Skills & Agents milestone 2026-08-31 08:06:42 +00:00

Claude added the Kind/Enhancement

labels 2026-08-31 08:06:42 +00:00

Defame1297 referenced this issue from a commit

2026-09-01 13:09:28 +00:00

fix(bin): restore prototype's deleted anti-patterns and two routing triggers