holocron/docs/issues/0018-factory-write-skill.md

# 0018 — factory/write-skill (bootstrap skill)

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

## What to build

### Phase 1: `write-skill`

Build `write-skill` — the second bootstrap skill. Once complete, it is used to author all subsequent SKILL.md files in Chunk 3.

**Trigger description** (from skills index): "Write a new skill for X, create a SKILL.md that does Y"

**Key constraints:**
- Produces a complete SKILL.md following the authoring standard in `docs/notes/skill-implementation-workflow.md`
- Validates trigger description against explicit, implicit, and negative test queries before completing
- Flags if the proposed skill overlaps with an existing skill in the library
- Skill file: `.agents/skills/write-skill/SKILL.md`; `metadata.category: factory`
- SKILL.md is hand-written (write-skill cannot author itself before it exists)
- Eval via `write-eval` (issue 0017)

### Phase 2: `write-docs`

Build `write-docs` — the first skill authored via `write-skill` itself (the factory eating itself for the first time). Implement immediately after phase 1 is complete and deployed.

**Trigger description** (from skills index): "Write documentation for X, document this module, create docs for this feature"

**Key constraints:**
- Skill file: `.agents/skills/write-docs/SKILL.md`; `metadata.category: implement`
- SKILL.md authored via `write-skill`; eval via `write-eval`
- Follow full per-skill workflow from `docs/notes/skill-implementation-workflow.md` (sub-agents for discovery, review, conflict check)
- Derives from code and spec; never invents behaviour

### Phase 3: Documentation convention

Define the canonical documentation convention for this repo — the missing input that `write-docs` currently defers to "user-specified or conventionally appropriate path." Without this, every `write-docs` invocation requires the user to re-decide where output goes.

**Opening action:** `/grill-me` session to resolve the convention before writing anything.

**Questions the grill must resolve:**
- What documentation types exist in this repo? (reference, guide, README section, inline comment, changelog entry, etc.)
- Where does each type live? (file paths, directory structure — e.g. does `docs/` own all prose, or do modules carry their own READMEs?)
- Global defaults vs. repo-specific overrides — what layer does the convention live at?
- What format standards apply per type? (required headers, prose vs structured, max length)
- Does `write-docs` need to be updated after the convention is defined, or does it reference it at runtime?

**Expected outputs:**
- `docs/notes/doc-convention.md` — the convention document (file/folder/content structure, per-type rules, override model)
- Update to `write-docs` SKILL.md output format section — reference the convention instead of deferring to "conventionally appropriate path"
- Update to `CONTEXT.md` if the convention becomes a standing repo-level principle

**No new SKILL.md for this phase** — this is a convention document, not a skill. If `write-docs` needs substantial changes after the grill, use `upgrade-skill`.

## Implementation notes

Follow the per-skill workflow defined in `docs/notes/skill-implementation-workflow.md` (produced by issue 0016).

**Known upstream sources to review:**
- `mattpocock/skills` — contains `write-a-skill`, the direct Pocock equivalent; review at current HEAD; record SHA in `source:` for any adopted content
- agentskills.io open standard — the SKILL.md format spec is the authoritative reference for what `write-skill` must produce; cross-reference against the standard before finalising output format constraints
- `bmad-method/bmad-method` — check for any skill-authoring or template-writing patterns

## Acceptance criteria

- [x] `.agents/skills/write-skill/SKILL.md` exists; `metadata.category: factory`; authoring standard met
- [x] Trigger description validates against explicit, implicit, and negative test queries
- [x] `.agents/evals/factory/write-skill/eval.yaml` exists; produced via `write-eval`
- [x] `install.sh` deploys `write-skill` to `~/.agents/skills/`
- [ ] **HITL:** human runs behavioral test: invoke "write a new skill for X" and verify the produced SKILL.md meets the authoring standard
- [ ] **HITL:** human reviews SKILL.md and eval before committing
- [x] Per-skill process followed for both phases (see `docs/notes/skill-implementation-workflow.md`)
- [x] Trigger description for each skill tested against explicit, implicit, and negative queries before body written
- [x] `when:` frontmatter field present in both SKILL.md files
- [x] `source:` and `references:` fields correctly populated or absent
- [x] eval.yaml for each skill contains all 5 required test types
- [x] Body ≤500 lines for each skill
- [x] Phase 2 (`write-docs`) is the first skill produced end-to-end by the factory
- [x] `docs/spec/overview.md` updated to reflect both skills deployed
- [ ] **Phase 3:** `/grill-me` session completed; grill output committed
- [ ] **Phase 3:** `docs/notes/doc-convention.md` written and committed
- [ ] **Phase 3:** `write-docs` SKILL.md output format updated to reference the convention (via `upgrade-skill` if substantive)
- [ ] **Phase 3:** `CONTEXT.md` updated if convention becomes a standing principle

## Blocked by

- 0016 (grill defines per-skill workflow)
- 0017 (`write-eval` needed to produce the eval for this skill)

## Handoff — Phase 1

**Status:** complete — pending HITL behavioral test (acceptance criteria steps 5–6)

**Files produced:**
- `.agents/skills/write-skill/SKILL.md`
- `.agents/evals/factory/write-skill/eval.yaml`

**Key decisions:**
- Scope: new-skill creation + placeholder→canonical conversion only. Updating/fixing existing skills → `upgrade-skill` (separate skill in the index).
- Trigger validation (3 cases) is a named gate in write-skill's process before body content is written.
- `write-eval` is step 7 of write-skill's process — the skill invokes it automatically. HITL prompt is step 8.
- Self-authored (no `source:` field); `references:` cites agentskills.io best-practices and optimizing-descriptions.
- speckit-agent-skills (dceoy) excluded — AGPL-3.0 copyleft.
- Role is self-contained (no reference to workflow doc) so it can be used standalone after chunk 3.

**Open threads:**
- HITL behavioral test for write-skill: open a fresh session, invoke "write a new skill for X" in this repo context, verify trigger is tested before body, per-section walk-through happens, write-eval is invoked, HITL prompt appears.
- Phase 2 HITL behavioral test: open a fresh session, invoke "write docs for X" or "document this module", verify file-approval gate fires before any reading, gap check step appears, full section shown before confirmation gate, Reader Testing step present.

**Next session start:**
- Load: `CONTEXT.md`, `docs/notes/skill-implementation-workflow.md`, `docs/issues/0019-factory-skills-remaining.md`
- First action: HITL behavioral tests for write-skill (phase 1) and write-docs (phase 2) if not yet done, then begin issue 0019 — start with `write-adr` (must be verified before design skills issue 0020 begins)

---

## Handoff — Phase 2

**Status:** complete — pending HITL behavioral test

**Files produced:**
- `.agents/skills/write-docs/SKILL.md`
- `.agents/evals/implement/write-docs/eval.yaml`

**Key decisions:**
- File-approval gate before reading: user names specific files, or skill proposes candidates and waits for approval — enforces governance scope discipline.
- Gap check before drafting: presents extracted behaviour, asks user to fill only what code doesn't explain — prevents invented content.
- Stage skipping: allowed with explicit user request + one-sentence logged reason (hybrid per synthesis grill decision).
- Confirmation gate: shows full revised section before gate fires, not just the diff (per synthesis grill decision).
- Surgical edits only + per-round delta summary (no hard iteration cap, delta summary keeps cumulative change reviewable).
- Reader Testing: scoped sub-agent receives only finished doc + questions — no source files (minimum data exposure per governance conflict 1).
- Sources adopted: anthropics/skills doc-coauthoring (Reader Testing stage, surgical-edit constraint, gap-check), mattpocock/skills write-a-skill (trigger pattern, checklist items), bmad-code-org/BMAD-METHOD bmad-advanced-elicitation (confirmation gate). bmad infrastructure (CSV registry, party mode) explicitly excluded.
- Rejected mattpocock 100-line limit — project convention (500 lines) takes precedence; noted in inline source comment.
- Prompts-as-code governance obligation satisfied: SKILL.md committed to repo; version control is the enforcement mechanism.

**Open threads:**
- Documentation convention: scoped to Phase 3 of this issue — see "What to build" above. `write-docs` output format section will be updated once the convention is defined.
- HITL behavioral test: see above.