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/notes/factory-integration-decisions.md

@@ -42,7 +42,7 @@ Categories are expressed via `metadata: category:` in SKILL.md frontmatter. Defi
 | `iac` | write-ansible-role, write-terraform-module, write-k8s-manifest, write-docker-compose, proxmox-vm-spec, iac-security-review, write-molecule-test — **global optional** |
 | `gitea` | setup-gitea-mcp, post-pr-review, create-issue — **global optional** |
 | `cross-cutting` | zoom-out, caveman, session-handoff, governance-check, git-guardrails, git-commit-message |
-| `factory` | write-a-skill, write-adr, write-workflow, write-eval, validate-skill, upgrade-skill, write-issue-spec |
+| `factory` | write-skill, write-adr, write-workflow, write-eval, validate-skill, upgrade-skill, write-issue-spec |
 | `roles` | architect, developer, reviewer, security, qa, ops — **Chunk 5** |
 
 ### 3. SKILL.md authoring standard (full)

docs/notes/skill-implementation-workflow.md

@@ -90,7 +90,7 @@ Write the `description:` frontmatter field first. Test it against three cases be
 2. Implicit invocation — user describes the task without the trigger phrase
 3. Negative case — adjacent task that must NOT activate this skill
 
-Do not proceed to the body until all three pass.
+For each case, output an explicit **PASS** or **FAIL** result. Do not proceed to step b until all three show PASS. Including the description inside the section walk-through (step b) does not satisfy this gate — it must be a standalone test-then-proceed step with per-case verdicts. If any case fails, revise the description and re-test before continuing.
 
 **b. Per-section options walk-through**  
 Before writing anything, walk through each body section with the human. For each section:
@@ -109,7 +109,11 @@ Populate after upstream review. Two distinct fields:
 - `references:` — general citations (research papers, documentation, standard specifications). Present only if the skill cites external research.
 
 **d. eval.yaml** (sub-agent)  
-Spawn an agent to produce the eval via `write-eval`. Co-located at `.agents/evals/<category>/<skill-name>/eval.yaml`. Must contain all five required test types (see Eval schema below).
+Invoke `write-eval` in two steps to preserve its confirmation gate:
+1. Sub-agent proposes test cases and returns the plan to the main conversation.
+2. Human confirms the plan; then sub-agent writes the file.
+
+Do not pass pre-designed test cases directly to a write agent — that collapses the plan-then-confirm gate into a single step, bypassing write-eval's own constraint. Co-located at `.agents/evals/<category>/<skill-name>/eval.yaml`. Must contain all five required test types (see Eval schema below).
 
 **e. HITL behavioral test**  
 Human opens a fresh Claude session, invokes the skill with its trigger phrase, and verifies output. Do not batch more than 2–3 skills before running behavioral tests — output volume must stay within genuine human review capacity. An approval that cannot be meaningfully evaluated is not an approval.