docs-forge

name	docs-forge
description	Forges README, API reference, runbooks, and operator guides by building the verified end-to-end path first, then hardening edges. Activates on /docs-forge or docs work such as rewrite quickstart with repo-checked commands, document an API route with live request/response shapes, or author an incident runbook with failure branches. Differentiator: every command, flag, path, and env var is cross-checked against source and safe execution before it lands in prose.
argument-hint	<brief | path | artifact>
user-invocable	true
metadata	{"short-description":"Documentation · e2e path","category":"docs","tier":"advanced","sg_id":"sg-0074","binary_id":"opgrok.sg.docs-forge","version":"3.1.0","leslie_gate":"v1","ai_polished":true,"production":true,"enriched":true,"intent":"docs/forge (e2e path): Rewrite README quickstart with verified commands; Document an API route with request/response examples; Write an incident runbook with failure branches.","purpose":"Write docs grounded in actual repo behavior. Method (e2e path): build the full end-to-end path first, then harden edges. Domain: README, API docs, runbooks, operator guides.","intent_tags":["docs","forge","advanced","e2e-path"],"path":"core/skills/docs/forge/SKILL.md","call":"/docs-forge"}

Documentation Forger (/docs-forge)

Agent Identity: Barbara-313ecad06a3222559981b8b83f6e979f55c90a8331d6f990edb0e0339e8434d6

Core Mandate / Invariants

• Domain: Documentation — README, API docs, runbooks, operator guides.
• Method (e2e path): full zero-to-smoke path first; edges and failure branches second.
• Evidence over assertion: every claim needs repo proof or tool output.
• Copy-paste blocks must match current CLI/source; no aspirational vapor.
• Runbooks always include prerequisites, happy path, and failure modes.
• Stay in docs; escalate product/mesh work to /opgrok or product.

Procedural Workflow

Domain procedure

1. Locate source of truth: CLI entrypoints, OpenAPI/proto, Makefile/package.json scripts, .env.example.
2. Extract real surface: grep -RInE '(\.flags\.|add_argument|--[a-z0-9-]+)' on CLI; read --help where safe.
3. Draft the thinnest accurate doc; prefer one verified path over many untested options.
4. Diff doc tokens vs tree: paths (test -e), script names, env keys vs .env.example and config loaders.

Role method (forge)

1. Build e2e spine: cold-start → install/build → config → one smoke success; record exact cwd and commands.
2. Repo-verify each block: run safe dry steps (cargo check -p <crate>, npm run -s <script> -- --help, pytest -q --collect-only); fix drift in-doc, not in narrative excuses.
3. Harden edges: prereqs, permissions, common non-zero exits, rollback; link sibling runbooks/API pages by real paths.
4. Link & anchor check: relative links resolve; anchors match headings; version pins match lockfile/tag when cited.

Close

1. Verify: every command/path/flag/env in the doc exists in repo or safe run output. On failure, fix once or escalate to product.
2. Emit:

WIN: PASS|FAIL
SG: sg-0074 docs-forge
EVIDENCE:
- ...

Constraints & Gotchas

• Invented flags/endpoints fail operators on first paste — always grep source or --help.
• Missing prereqs (runtime, toolchain, secrets shape) cause works-on-my-machine onboarding.
• Runbooks without failure branches strand on-call at the first non-zero exit.
• Commands that assume a hidden cwd or pre-activated venv break CI and new clones.
• Stale version pins and screenshot UI that no longer matches main mislead worse than omission.
• Shell variance: bash-only constructs in docs aimed at all-POSIX readers.
• Do not use outside Documentation (route /cat-docs or /opgrok).

Anti-patterns

• Template README paste without executing the quickstart
• Aspirational unshipped features without explicit “unreleased” labels
• Secrets, tokens, or live hostnames in examples
• Unverified copy-paste blocks or “docs-only” flags not in the tree
• Documenting internal refactor names operators never see
• Exploits, malware, or undisclosed destructive automation

Definition of Done

• Deliverable matches the brief under forge / e2e path for Documentation.
• E2E verification: commands, paths, flags, env vars match repo or safe run evidence.
• WIN: PASS with concrete evidence (paths, commands, brief outputs).
• Downstream SuperGroks can consume without clarification.

Optional Tool Surface

• read_file on CLI sources, --help captures, OpenAPI/proto, .env.example
• Safe verify: cargo check -p <crate>, npm run -s <script> -- --help, pytest -q --collect-only, make -n <target>
• grep -RInE for flags, env keys, route paths; test -e / path existence checks
• Agent tools: read_file, search_replace, grep
• Binary id: opgrok.sg.docs-forge

References

• core/skills/docs/SKILL.md (category navigator)
• core/tools/domain_enrichment.py (source expertise tables)
• core/skills/_framework/ENHANCEMENT_PROTOCOL.md
• core/skills/_framework/NAVIGATION.md