feat: implement issue 0018 phase 2 — write-docs skill (first factory output)

Produces write-docs via the write-skill factory. First skill authored
end-to-end by the factory (SKILL.md via write-skill, eval via write-eval).

- Add .agents/skills/write-docs/SKILL.md (category: implement)
- Add .agents/evals/implement/write-docs/eval.yaml (6 trigger + 3 output tests)
- Remove write-a-skill placeholder (superseded by write-skill)
- Extend issue 0018 with Phase 3 (doc convention, grill-first)
- Tighten workflow steps 5a and 5d based on session lessons
- Update factory-integration-decisions: write-a-skill → write-skill
- Add 2 LESSONS.md entries (trigger gate, write-eval sub-agent bypass)
- Update docs/spec/overview.md and ROADMAP

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

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

@@ -31,6 +31,26 @@ Build `write-docs` — the first skill authored via `write-skill` itself (the fa
 - 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).
@@ -48,14 +68,18 @@ Follow the per-skill workflow defined in `docs/notes/skill-implementation-workfl
 - [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
-- [ ] Per-skill process followed for both phases (see `docs/notes/skill-implementation-workflow.md`)
-- [ ] Trigger description for each skill tested against explicit, implicit, and negative queries before body written
-- [ ] `when:` frontmatter field present in both SKILL.md files
-- [ ] `source:` and `references:` fields correctly populated or absent
-- [ ] eval.yaml for each skill contains all 5 required test types
-- [ ] Body ≤500 lines for each skill
-- [ ] Phase 2 (`write-docs`) is the first skill produced end-to-end by the factory
-- [ ] `docs/spec/overview.md` updated to reflect both skills deployed
+- [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
 
@@ -79,9 +103,34 @@ Follow the per-skill workflow defined in `docs/notes/skill-implementation-workfl
 - Role is self-contained (no reference to workflow doc) so it can be used standalone after chunk 3.
 
 **Open threads:**
-- HITL behavioral test: 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 (`write-docs`): first skill authored end-to-end by the factory. Follow full per-skill workflow from `docs/notes/skill-implementation-workflow.md`.
+- 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/0018-factory-write-skill.md`
-- First action: HITL behavioral test for write-skill, then begin phase 2 (`write-docs`) using write-skill
+- 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.