docs: issue 0016 — skill implementation workflow grill

Produces docs/notes/skill-implementation-workflow.md with agreed conventions
for all Chunk 3 skill issues (0017–0028). Key decisions:

- Per-skill process: source discovery (sub-agent) → source review with
  licence/security check (sub-agent) → conflict check vs constitution +
  factory principles (sub-agent) → synthesis grill → co-write iteratively
- Bootstrap: write-eval (hand-written) → write-skill (hand-written) →
  write-docs (first factory-authored, phase 2 of 0018) → everything else
- Upstream review changed from per-chunk-start to per-skill
- `when:` and `references:` frontmatter fields added to authoring standard
- Sub-agent usage prescribed as named steps in the workflow
- HITL: human reviewed and approved conventions

Updates: PRD implementation decisions; issues 0016–0028 with specific
acceptance criteria; docs/spec/overview.md; ROADMAP Chunk 3 housekeeping note
(bootstrap order, cadence, acceptance criteria status); CONTEXT.md Source field
(per-skill cadence, references: companion field); LESSONS.md with three patterns
from the grill session.

Post-grill additions (same session): Step 6 (session handoff) added to the
workflow; handoff section appended to issue 0016; handoff checklist item added
to Chunk 3 closure issue (0028).

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

docs/prd/chunk-3-skills-library.md

@@ -1,6 +1,6 @@
 # PRD: Chunk 3 — Skills Library Rebuild
 
-**Status:** Ready for issues  
+**Status:** In progress — 0015 ✅, 0016 ✅  
 **Produced by:** grill-with-docs session, 2026-05-17  
 **Prerequisite:** AGENTS.md refactor issue must be completed before skill implementation begins
 
@@ -86,10 +86,10 @@ source:
 Multiple entries for skills combining patterns from multiple upstreams. Absence of `source:` means self-authored original. Single-source skills use a single-item array for schema consistency.
 
 ### Upstream review cadence
-At the start of each chunk: grep all `source:` fields, check the listed repos for commits since `updated:`, decide whether to pull changes in. After the roadmap is complete (post Chunk 7): quarterly calendar-based review. Cadence is a human responsibility — no tooling required until Chunk 6.
+Per-skill (not once at chunk start): during source review for each skill, check listed repos for commits since `updated:`, decide whether to pull changes in using the pull criteria documented in `docs/notes/skill-implementation-workflow.md`. After the roadmap is complete (post Chunk 7): quarterly calendar-based review. Cadence is a human responsibility — no tooling required until Chunk 6.
 
 ### Factory bootstrap order
-`factory/write-eval` is the first skill built in Chunk 3, with a hand-written eval for itself. Every subsequent skill in Chunk 3 gets an eval written via `write-eval`. Eval YAML files live in `.agents/evals/<category>/<skill-name>/eval.yaml`. CI enforcement of evals is Chunk 6 — the files exist and document expected behaviour before then.
+`factory/write-eval` is the first skill built in Chunk 3, with a hand-written eval for itself. `factory/write-skill` is second, also hand-written. `implement/write-docs` is the third skill — phase 2 of issue 0018, the first skill authored via `write-skill` itself (the factory eating itself for the first time). Every subsequent skill in Chunk 3 uses `write-skill` for SKILL.md authoring and `write-eval` for eval production. Eval YAML files live in `.agents/evals/<category>/<skill-name>/eval.yaml`. CI enforcement of evals is Chunk 6 — the files exist and document expected behaviour before then.
 
 ### Skill taxonomy — phase × domain matrix
 Phase axis: `design`, `factory`, `implement`, `test`, `review`, `deploy`, `operate`, `cross-cutting`. Domain axis: `iac` (tool-specific). Cross-cutting skills have no single phase home. Paths remain flat per ADR-0009; category expressed in `metadata.category` frontmatter only. Role skills (`roles/`) are Chunk 5.
@@ -123,7 +123,7 @@ Phase axis: `design`, `factory`, `implement`, `test`, `review`, `deploy`, `opera
 | `implement-feature` | `implement/implement-feature` | New |
 | `tdd` | `implement/tdd` | Preserved; frontmatter + standard added |
 | `refactor` | `implement/refactor` | New |
-| `write-docs` | `implement/write-docs` | New |
+| `write-docs` | `implement/write-docs` | Phase 2 of issue 0018 — first factory-authored skill |
 | `diagnose` | `implement/diagnose` | Preserved; frontmatter + standard added |
 
 **Test (3):** `write-tests`, `generate-test-data`, `review-test-coverage` — all new.
@@ -173,7 +173,10 @@ Issues contain: link to parent PRD (inherited why), EARS acceptance criteria, br
 Skills reference "linked issue" generically. In the file-based phase (`docs/issues/`), skills check for a matching `docs/issues/NNNN-*.md`. When Gitea MCP is configured, skills use it instead. The active backend is determined at runtime by MCP availability, not a config flag. An ADR (0011) documents this decision. Gitea-specific skills (`setup-gitea-mcp`, `post-pr-review`, `create-issue`) are a provider adapter at `providers/gitea/` — not part of the core library.
 
 ### Authoring standard for all skills
-Every SKILL.md carries: `name`, `description` (trigger — written and tested first), `version`, `updated`, `metadata.category`, `source` (array, if upstream-derived). Body sections: role, when/when-not, required inputs, constraints, process, output format, failure handling, self-check. Body under 500 lines. XML tags only for skills with ≥3 logical sections and 500+ tokens.
+Every SKILL.md carries: `name`, `description` (trigger — written and tested first), `version`, `updated`, `when` (when the skill is invoked — deferred to Chunk 4 for full bidirectional reference convention), `metadata.category`, `source` (array, if upstream-derived), `references` (array, if external citations needed). Body sections: role, when/when-not, required inputs, constraints, process, output format, failure handling, self-check. Body under 500 lines. XML tags only for skills with ≥3 logical sections and 500+ tokens.
+
+### Sub-agent usage in skill implementation
+Skills are implemented using the per-skill workflow in `docs/notes/skill-implementation-workflow.md`. Sub-agents handle source discovery, source review (including licence and security checks), conflict checking against the constitution and factory principles, and eval writing. This keeps the main context lean and ensures each step is independently reviewable. The synthesis grill and HITL behavioral test are human-in-the-loop steps that cannot be delegated.
 
 ### Changelog tooling
 `git-cliff` adopted as the deterministic changelog generator. Config (`cliff.toml`) added to this repo in Chunk 3; CI integration in Chunk 6. `review/changelog-entry` skill handles prose release notes for cases where conventional commit messages alone are insufficient. git-cliff is selected over release-please (GitHub-only, incompatible with Gitea) and conventional-changelog (Node.js dependency, less actively maintained).