Add a handoff-readiness skill that catches what would mislead a cold agent

[ooloth]

Current state

An agent starting cold on hub can read the docs carefully and still write code against subsystems that do not exist, because the docs describe them as present. Nothing checks for this, and the person least able to spot it is whoever wrote the docs: you read what you already believe into every file.

The defect category hub produces is a doc, ADR, or issue asserting that something is built when no source backs it. docs/decisions/019-drop-task-model-filesystem-sessions.md:3 is the clearest live case, marked "Status: Accepted and implemented" for a filesystem session model that has no corresponding code.

ooloth/puzzles has a working version of this check at .claude/skills/prep-for-codebase-handoff/SKILL.md. About half its scan categories transfer; the rest target doc structures hub does not have (guarantees/, unfinished.md, constraints.md, standards/).

Ideal state

• A project skill reports, on request, what would mislead an agent picking hub up cold
• A subagent with no briefing reads the repo and reports what it would work on next and what misled it, because only a stranger can find what confuses a stranger
• Scans cover what a stranger cannot see, since a stale file reads as current: claims that a subsystem is built where no source backs it, questions answered but still open, docs contradicting a recorded decision, and issue bodies naming things that no longer exist
• Every finding names a file and line, or an issue number
• The skill proposes fixes and waits for approval. It does not edit docs or code, and it does not touch GitHub issues
• The skill records which scan categories look hub-specific and which look portable to other repos

Open decisions

Deliberately left to whoever picks this up. Make each call and record it in the skill:

• Whether scans cover GitHub issues as well as docs. Two of hub's worst cases lived in issues. Note that gh issue view omits comments unless passed --comments, and issue relationships are only readable through GraphQL
• Whether the skill runs the binary to settle claims about behaviour that reading cannot settle
• What triggers it: wrapping up a session, starting a milestone, or both
• Whether the cold read runs on every invocation, given it costs several minutes and a large amount of context
• Which categories could be upstreamed to ~/.agents/standards/ so other repos share them rather than each forking a copy. Note the candidates; the extraction itself is not part of this issue

Out of scope

• Deterministic path and identifier checks, which belong in a script rather than a skill
• Fixing the current crop of stale claims. Phase 1.2 — Inventory built vs. planned subsystems so agents stop coding against integration points that don't exist #299 covers the built-vs-planned inventory; this issue is about catching the next ones
• Duplicating the existing global scan-standards and scan-gaps skills. Those check conventions and find untracked opportunities; this one asks whether a stranger would be misled

Starting points

• /Users/michael/Repos/ooloth/puzzles/.claude/skills/prep-for-codebase-handoff/SKILL.md — the model to adapt; the cold-read prompt and the launch-everything-at-once structure transfer directly
• docs/decisions/019-drop-task-model-filesystem-sessions.md — the clearest instance of the category the skill exists to catch
• docs/questions/README.md — the six-section format and evidence tiers the scans check claims against

Hub has no project skills yet. .claude/skills symlinks to .agents/skills, which is empty.

QA plan

1. Invoke the skill against hub as it stands — expect a report where each finding names a file and line or an issue number, and expect git status to show no modifications
2. Read the cold subagent's section — expect it to name what it would work on next and what told it to
3. Verify one reported finding by hand — expect it to be a real defect, not a deliberate choice the subagent lacked the context to recognise
4. Apply the proposed fixes, then invoke the skill again — expect the earlier findings gone, and the cold read to land on a sensible next task without being misled
5. Add a deliberate false claim to a doc, naming a function that does not exist, then invoke the skill — expect it caught and reported
6. Confirm across the whole run that no doc, code file, or GitHub issue was modified

Done when

The skill reports findings that name a file and line, and after its proposed fixes are applied a cold agent orients from a natural entry point and picks a defensible next task without being misled by anything the repo asserts.

[ooloth]

Sibling: #333 covers the deterministic path and command checks that shouldn't need a skill's judgement. Independent of this issue and workable in either order.