Skip to content

zeikar/hyperclaude / skills/hyper-docs-loop

hyper-docs-loop

Unverified

Use when documentation should be brought into accuracy with the code in one gesture — docs-review → fix → re-review, repeated until no blocking findings remain. Also when the user invokes /hyperclaude:hyper-docs-loop. For manual round-by-round control use /hyperclaude:hyper-docs-review + manual edits instead.

FileKindSize
SKILL.mdskill md17.7 KB
references/failure-protocol.mdmarkdown9.7 KB

references/failure-protocol.md

View on GitHub
# hyper-docs-loop — failure & recovery protocol

Operational backstops for `hyper-docs-loop`. The shared cross-loop protocol (spawn contract, reply transport, corrective/transport-failure skeleton, shared anti-patterns) lives in `${CLAUDE_PLUGIN_ROOT}/references/loop-protocol.md`. This file is the docs-loop's binding layer: the agent role (`documenter`), the structured per-finding reply schema, the schema-gate accept rule, the semantic finding-map post-acceptance validation, the named reports, what a transport failure preserves, the Claude seat's bindings, and the docs-loop-specific anti-patterns. SKILL.md Step 0 Reads both files plus `${CLAUDE_PLUGIN_ROOT}/references/reviewer-seat.md`.

## Binding declarations

- **Agent role:** `documenter` — spawned once at SKILL.md Step 5 as `subagent_type: "hyperclaude:documenter"`, lazily, on the FIRST round that carries blocking `### Findings`; every later round is addressed to the captured `agent_id`. A run whose first review is clean spawns none. It is the same agent `hyper-docs-sync` dispatches for UPDATE/CREATE mode; the loop's spawn-prompt contract overrides the dispatch context to this loop's structured-findings mode.
- **Reply shape:** the structured findings-map schema — for EVERY cited finding, its own `finding:` / `status:` / `files-changed:` / `verification:` / `notes:` block, delivered as the documenter's FINAL TEXT. There is no output file.
- **Accept rule (schema gate):** a documenter reply **FAILS** if any of the following are true:
  - It has no per-finding block (the structured-schema fields are entirely absent).
  - It is missing a block for any cited finding.
  - Any `status:` value is not exactly `fixed` or `not-applicable` (no synonyms, no extra words).
  - A `notes:` field is omitted when `status: not-applicable` (the reason is required; an empty or missing `notes:` fails the gate).

  Small extra prose (a one-line summary, a brief comment before or after the blocks) is tolerated and does not fail the gate. A diff dump, patch block, or verbatim source-body echo FAILS the gate **even when all required schema fields are present** — the documenter's "No diff dump" rule is enforced here, not weakened. There is no single output-file path to verify: the gate applies to the reply structure only, and the lead performs no filesystem existence check here.
- **Post-acceptance validation:** the semantic finding-map check below (every cited blocking finding maps to `status: fixed` OR `status: not-applicable` with a non-empty `notes:` reason).
- **Named-loop-report strings:** `hyper-docs-loop reply-contract failure`, `hyper-docs-loop documenter format, iter N`, `hyper-docs-loop unparseable review, iter N`, `hyper-docs-loop bridge failure, iter N`, `hyper-docs-loop fix loop`, `hyper-docs-loop transport failure`, `hyper-docs-loop reviewer-seat failure, iter N`.
- **Reviewer seat (Claude):** the `reviewer` agent at `reviewer_agent_id`, driven per `reviewer-seat.md` **Reply and validation** — accept rule `^WROTE: <exact minted artifact path>\s*$`, then `[ -s "<minted path>" ]`, then the artifact check's docs-review form, with ONE corrective for the whole pipeline (its reply re-enters at the accept rule). A second failure, or a reviewer spawn / `SendMessage` transport failure, STOPs with **"hyper-docs-loop reviewer-seat failure, iter N"**: the docs tree stays as the documenter last touched it (surface `git status --short`); the report surfaces the `Reviewer seat:` line and the minted path (renamed `<path>.rejected` on any of these STOPs, when the file exists).
- **Transport failure:** binds the shared transport-failure skeleton for the documenter. This loop commits nothing, so whatever a run produced lives only in the working tree. Under **"hyper-docs-loop transport failure"**: PRESERVE any uncommitted doc edits exactly as the documenter left them (no restore, no re-spawn), surface them (`git status --short`), and point the user at `/hyperclaude:hyper-docs-review` + manual edits to finish the job. The two halves differ only in what ran:
  - A Step 5 spawn that **returns no usable `agent_id`** (an ambiguous failure counts here), or a later round's **failed `SendMessage`** to the documenter: the documenter ran — the lazy spawn's own prompt carries that round's findings, and later rounds follow earlier rounds' edits — so it may already have edited the cited docs. Treat the docs tree as potentially mutated and report the edits as potentially present. Never assume the tree is unmodified.
  - A Step 5 spawn that **fails outright** is the same STOP under the same report name, but nothing ran and so this run produced no doc edits: state that plainly instead of implying edits that cannot exist.

  SKILL.md's spawn and fix-round failure branches point here rather than restating either half.

## Schema-gate correctives

The schema gate (declared above, applied at SKILL.md Step 5) is the accept condition for EVERY documenter reply: the first fix round's spawn `<result>`, any corrective redo, and every later round's `<result>`.

On any gate failure, send ONE corrective:

```
SendMessage({
  to: "<agent_id>",
  summary: "Reply contract: structured schema only",
  message: "<re-state: for every cited finding emit finding:/status:/files-changed:/verification:/notes: fields on their own lines; status must be exactly 'fixed' or 'not-applicable'; notes: is required when status: not-applicable; no diff dump, no patch block, no source-body echo; a small prose summary is tolerated but must not replace the schema>"
})
```

If the next reply still fails the gate → STOP (**"hyper-docs-loop reply-contract failure"**).

## Fix-validation redo pipeline (SKILL.md Step 5 failure handling)

**The ordered pipeline** every documenter reply must pass (named inline in SKILL.md Step 5): (1) **schema gate** → (2) **semantic finding-map check**: the lead reads the documenter reply and confirms that EVERY cited blocking finding maps to `status: fixed` OR `status: not-applicable` with a non-empty `notes:` reason. A corrective redo re-enters the pipeline from the schema gate — never "just the finding-map check". The budget is per stage: exactly ONE corrective redo each, then STOP.

There is **NO git-working-tree / no-op / `.bak` / restore mechanism**. A documenter that applies no real change is bounded by the Step 6 cap (the loop re-reviews and re-issues findings until convergence or the cap, then STOPs with the cap report) — reasserting a git-diff gate here is an anti-pattern and is intentionally not a separate failure path.

**Gate failure in Step 5:** apply the corrective + escalation above (escalating to **"hyper-docs-loop reply-contract failure"** if it still fails).

**Semantic finding-map check (stage 2 of the pipeline):** the lead reads the documenter reply in context and verifies that each cited blocking finding is accounted for. If one or more findings are unmet (status missing, or `fixed` but the lead judges the explanation impossible, or the required `notes:` for `not-applicable` is absent or empty): send ONE corrective `SendMessage` to `agent_id`, re-issuing only the unmet findings and instructing the documenter to address them. Its reply re-enters the FULL pipeline: schema gate → semantic finding-map check. If the redo still fails the semantic check → STOP (**"hyper-docs-loop documenter format, iter N"**), surfacing the unmet findings for manual triage. The loop does NOT auto-restore — the docs tree is left as the documenter last touched it.

**Invalid-finding path:** a finding the documenter returns as `not-applicable` with a non-empty `notes:` reason is treated as **addressed** for gate purposes and does not block the loop. The next re-review is the arbiter: if the reviewer drops the finding the loop continues normally; if the reviewer re-raises it, it re-enters the normal loop and counts toward the cap.

## Anti-patterns (docs-loop specific)

The cross-loop anti-patterns (passing `name:` at spawn, re-spawning fresh each round, seating a Claude reviewer outside the seat rule, inlining the shared contract) live in `${CLAUDE_PLUGIN_ROOT}/references/loop-protocol.md`; the seat's own list lives in `reviewer-seat.md`.

Docs-loop-specific:

- Committing or pushing from the documenter. The documenter touches only the working tree; the orchestrating skill decides when to commit.
- Letting the documenter invoke codex or `scripts/codex-bridge.mjs`. The documenter never acts as reviewer.
- Letting the documenter edit source code, tests, scripts, or config files to make a doc claim "true". The doc is what changes; if the doc was actually right, the documenter reports `status: not-applicable` with a `notes:` reason.
- Changing `docs_target` mid-run — substituting one `--docs-path` for another, swapping `--docs-path` for `--docs-dir`, or omitting it on a resumed iteration. `docs_target` is the fixed, invariant loop target every iteration; the bridge requires it on resume too.
- Auto-fixing items from `### Gaps`, `### Broken Or Suspect Links`, or `### Cross-Doc Inconsistencies`. Only `### Findings` drives fix rounds; the other three sections are reported in the final Step 7 summary and resolved by the user manually. Sending those items to the documenter as if they were `### Findings` is a scope violation of this loop's contract.
- Reasserting a git-state / no-op gate. A stuck or no-change documenter is bounded by the Step 6 cap — a separate no-op detection path is an anti-pattern.
- Gating on label vocabulary instead of meaning. Classify by MEANING regardless of label: a `### Findings` item blocks if it concerns accuracy / drift / actively misleading claims, regardless of the severity label the reviewer assigned; pure style/nits do not block.
- Treating a `resume-failed` or `fallback` round as invalid. Such a round is still a valid loop iteration and counts toward the cap, but it MUST be flagged in the final report so the human can assess continuity.
rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization.Stars: 467kUpdated Claude CodeCodexVerifiedInstall
academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file).Stars: 196kUpdated Claude CodeCodexUnverifiedInstall
doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.Stars: 196kUpdated Claude CodeCodexVerifiedInstall