refactor: write-skill phase 1 refactor — grill, implementation, lessons

Complete 2026-05-18 workstream for write-skill refactor (issue 0018 phase 1).

Grill output (handoff in docs/issues/0018-factory-write-skill.md):
- 6-section standard replaces 8: Role and When/When not dropped (not in
  agentskills.io spec; description carries trigger scope and negatives)
- Frontmatter reduced to 3 fields; provenance moves to META.md
  (progressive disclosure — not loaded at every skill scan)
- SKILL-TEMPLATE.md and META-TEMPLATE.md as authoritative copy-fill artifacts
- CATEGORIES.md as self-contained category reference in skill directory
- Copy and fill explicitly split into separate process steps for determinism

New files in .agents/skills/write-skill/:
- SKILL-TEMPLATE.md — 6-section template with XML blocks and inline examples per section
- META-TEMPLATE.md — provenance schema with inline-commented YAML; source vs references explicit
- CATEGORIES.md — self-contained category table (no runtime dependency on factory docs)
- META.md — write-skill's own provenance (v1.1, self-authored)

SKILL.md rewritten: 8-step process, XML blocks (<requirements>, <steps>, <checks>),
3-field frontmatter, copy-then-fill steps explicit.

Supporting docs updated:
- skill-implementation-workflow.md: SKILL-TEMPLATE.md as authoritative template;
  source:/references: now reference META.md; when: marked resolved
- factory-integration-decisions.md: frontmatter spec corrected
- ROADMAP.md: authoring standard description updated
- CONTEXT.md: Source field entry corrected; META.md added to glossary
- docs/spec/overview.md: 2026-05-18 refactor entry added
- docs/issues/0018: handoff status updated; acceptance criteria marked complete

LESSONS.md: 3 entries added in grill session (cargo-culted body sections,
provenance fields in frontmatter, copy-fill determinism) + 1 from implementation
(planning meta-commentary does not belong in deployed artifacts).

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

docs/notes/factory-integration-decisions.md

@@ -53,7 +53,8 @@ All skills — new and rebuilt — must follow this standard:
 - `name:` — matches directory name
 - `description:` — trigger-tested before writing the body (explicit, implicit, negative cases)
 - `metadata: category:` — from the category table above
-- `metadata: version:` — semantic version; increment on meaningful changes
+
+`version:`, `updated:`, `when:`, `source:`, and `references:` are provenance/audit fields — they live in `META.md` alongside the SKILL.md (not in frontmatter). See `META-TEMPLATE.md` in `.agents/skills/write-skill/` for the META.md schema.
 
 **Body required sections:**
 - Constraints (highest-ROI element — prevents overengineering)

docs/notes/skill-implementation-workflow.md

@@ -103,11 +103,13 @@ Do not write the SKILL.md until the human has confirmed every section. The synth
 **c. SKILL.md** (sub-agent)  
 Once all sections are confirmed, spawn a write agent to produce the SKILL.md using `write-skill` (or hand-write for bootstrap skills). The agent receives: trigger description, per-section decisions from step b, upstream content to incorporate, authoring standard (see below).
 
-**c. `source:` and `references:` fields**  
-Populate after upstream review. Two distinct fields:
+**c. META.md — `source:` and `references:` fields**  
+Populate `META.md` after upstream review. Two distinct fields:
 - `source:` — upstream provenance tracking (repo slug, commit SHA, files adopted with inline comments, updated date). Present only if content was adopted. Absence = self-authored.
 - `references:` — general citations (research papers, documentation, standard specifications). Present only if the skill cites external research.
 
+Both fields live in `META.md` alongside the SKILL.md — not in frontmatter. See `META-TEMPLATE.md` in `.agents/skills/write-skill/` for the full schema.
+
 **d. eval.yaml** (sub-agent)  
 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.
@@ -152,37 +154,29 @@ If this skill produced a cross-cutting observation — a pattern that appeared a
 ```yaml
 ---
 name: skill-name
-description: <trigger description — written and tested first>
-version: "1.0"
-updated: YYYY-MM-DD
-when: <when this skill is invoked — e.g. "invoked by /skill-name trigger">
+description: <trigger description — routing only; written and tested first; max 1024 chars>
 metadata:
   category: <design|factory|implement|test|review|deploy|operate|cross-cutting|iac>
-source:                              # omit entirely if self-authored
-  - repo: org/repo
-    commit: abc1234
-    files:
-      - path/to/file.md              # inline comment: what was taken
-    updated: YYYY-MM-DD
-references:                          # omit if no external citations
-  - <URL or citation>
+# allowed-tools: <add only when the skill has a narrow, well-defined tool surface; omit otherwise>
 ---
 ```
 
-`when:` is added to all Chunk 3 skills now; full bidirectional reference convention (reverse map, reference scanner) is deferred to Chunk 4 for refinement.
+Frontmatter contains only these fields. `version`, `updated`, `when`, `source`, and `references` are provenance/audit fields — they are not used for routing or runtime execution. They live in `META.md` alongside the SKILL.md, loaded only when needed. See `META-TEMPLATE.md` in `.agents/skills/write-skill/` for the META.md schema.
 
-`allowed-tools:` — optional field to restrict which tools the skill may invoke. Reduces token cost of tool definitions. Add when the skill has a narrow, well-defined tool surface.
+### Body sections
 
-### Body sections (required, in this order)
+Use `.agents/skills/write-skill/SKILL-TEMPLATE.md` as the authoritative structure reference. The template defines the required sections, correct order, XML grouping, and placeholder comments for each section.
 
-1. **Role** — one sentence: who the agent is when this skill is active
-2. **When to use / When not to use** — explicit inclusion and exclusion criteria; negative cases are as important as positive
-3. **Required inputs** — what must be present before the skill proceeds
-4. **Constraints** — non-negotiable rules; the highest-ROI section for preventing over-engineering
-5. **Process** — numbered steps (not bullets)
-6. **Output format** — exactly what the skill produces; structured if downstream workflow steps depend on it
-7. **Failure handling** — what to return if inputs are missing or a step fails; never silent failure
-8. **Self-check** — skill-specific correctness criteria the agent verifies before responding; must be concrete, not generic
+Summary (6 sections, in order):
+
+1. **Required inputs** — what must be present before the skill proceeds
+2. **Constraints** — non-negotiable rules; the highest-ROI section for preventing over-engineering
+3. **Process** — numbered steps (not bullets)
+4. **Output format** — exactly what the skill produces; structured if downstream workflow steps depend on it
+5. **Failure handling** — what to return if inputs are missing or a step fails; never silent failure
+6. **Self-check** — skill-specific correctness criteria the agent verifies before responding; must be concrete, not generic
+
+**Role** and **When to use / When not to use** are removed from the authoring standard. The description field carries trigger scope and negative cases (agentskills.io spec); Role is redundant when description + process provide adequate behavioral framing.
 
 **Size:** body ≤500 lines. Use XML tags only for skills with ≥3 logical sections and 500+ tokens; default to prose.
 
@@ -236,6 +230,6 @@ Upstream review happens per-skill during step 2, not once at chunk start.
 
 ## Open decisions carried forward
 
-- **`when:` full resolution** — Chunk 4 (bidirectional reference convention, reference scanner tooling)
+- **Bidirectional reference convention** — Chunk 4 (reference scanner tooling; reverse map "what files point to X?"). The `when:` field itself is resolved — it lives in `META.md` alongside every skill.
 - **PRD/issue template scope** — refined during `write-prd` (0020) and `write-issue-spec` (0019) implementation
 - **Merging `zoom-out` into architect role** — revisit at Chunk 5 grill