holocron/docs/issues/0027-cross-cutting-skills.md

0027 — Cross-cutting skills: session-handoff, governance-check, git-commit-message, improve-codebase-architecture, triage, zoom-out, caveman

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

What to build

The 7 cross-cutting skills (no single phase home). Three are new; four are preserved Pocock placeholders upgraded to the authoring standard. Authored via write-skill (0018), evals via write-eval (0017). caveman is kept as-is (no eval required — it is a formatting-only utility, not a content skill).

Skills, origins, and trigger descriptions:

Flat name	Origin	Trigger description
session-handoff	New	Session handoff, save context, pausing work
governance-check	New	Check this against governance rules, is this allowed
git-commit-message	New	Write commit message, conventional commit, git message
improve-codebase-architecture	Preserved; frontmatter + standard added	Improve architecture, refactor structure, codebase improvement
triage	Preserved; fix dead references; frontmatter + standard added	Triage this issue, categorise, prioritise
zoom-out	Preserved; frontmatter + standard added	Zoom out, big picture, what are we doing
caveman	Kept as-is	(token compression utility — no trigger change)

Key constraints per skill:

• session-handoff: captures current state, next steps, decisions with rationale, and linked issue reference; prompts LESSONS.md extraction before closing; does NOT manage docs/spec/ — spec is updated in-PR, not at handoff
• governance-check: validates proposed action against AGENTS.md (must reference AGENTS.md, not governance.md, now that AGENTS.md is the primary entry point post-0015)
• git-commit-message: conventional commits format; derives from diff; does not invent scope or type
• triage: remove dead references (AGENT-BRIEF.md, OUT-OF-SCOPE.md); add frontmatter and authoring standard sections
• zoom-out: add frontmatter and authoring standard; merge into architect role revisited at Chunk 5 grill (this note should appear in the SKILL.md as a when-not: constraint or a note in failure handling)
• caveman: no changes; no eval needed (not a content-generating 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 — original improve-codebase-architecture, triage, zoom-out, caveman placeholders; record SHAs for adopted content
• For new skills (session-handoff, governance-check, git-commit-message): search for prior art before writing from scratch

Acceptance criteria

• All 7 SKILL.md files exist at .agents/skills/<skill-name>/SKILL.md; metadata.category: cross-cutting; authoring standard met (except caveman — kept as-is)
• Dead references removed from triage and any other affected skills
• governance-check references AGENTS.md as the governance source (not governance.md); requires AGENTS.md refactor (0015) to be complete
• session-handoff explicitly excludes docs/spec/ management from its scope
• zoom-out SKILL.md notes the Chunk 5 grill revisit for potential merge into architect role
• source: fields populated for all Pocock-derived skills and any adopted upstream content
• Each new or refactored skill has a co-located eval at .agents/evals/cross-cutting/<skill-name>/eval.yaml via write-eval; caveman exempt
• install.sh deploys all 7 to ~/.agents/skills/
• HITL: human runs behavioral test for each new/refactored skill
• HITL: human reviews each SKILL.md and eval before committing
• (Further criteria to be refined after issue 0016 grill session)

Blocked by

• 0015 (AGENTS.md must exist before governance-check can reference it correctly)
• 0016 (per-skill workflow)
• 0017 (write-eval)
• 0018 (write-skill)