doc-this

Reverse-engineer a legacy codebase into ATDD-ready, traceable specifications. STRICTLY DESCRIPTIVE — documents what exists, never proposes or judges. Orchestrates Scout, Code Analyst, Detective, Architect, Writer, Reviewer plus optional Tracer, Visor, Data-Master, Design-System. Uses LSP for compiler-quality cross-file analysis when available, Understand-Anything graph as fallback. Classifies APIs public/private, catalogs HTTP/gRPC/CLI/message/UI/database surfaces, emits folder-per-unit specs with binary confidence (🟢 cited / 🔴 gap). Supports --incremental re-analysis via LSP blast-radius. Triggers: 'document this codebase', 'reverse engineer this system', 'extract requirements from legacy', '/doc-this'. NOT for docstrings. NOT for greenfield. NOT for proposing improvements, technical debt, or inventing NFRs. Delegates to doc-this-promote; the promoted specs feed whatever ATDD/TDD tooling the project already uses.

Fourth agent in the doc-this Discovery pipeline (synthesis). STRICTLY DESCRIPTIVE — synthesizes C4 diagrams, full ERD, integration map, spec-impact matrix as factual dependency map. Uses LSP (outgoingCalls, incomingCalls, goToImplementation, workspaceSymbol) for deterministic dependency mapping when available; falls back to Understand-Anything layers/edges or LLM synthesis. Emits external-surface.json catalog covering every HTTP/gRPC/WebSocket/CLI/message/UI/job surface — ui entries one-per-page from the file manifest (never 'pages grouped by module'; controls get subkind:control + mounted_in). Merges Data Master's kind:database entries for external/mixed DBs. Binary confidence: 🟢 (citation) / 🔴 (gap). Dispatched programmatically by doc-this after Detective — never auto-triggered by user phrasing; direct '/doc-this-architect' is for resume/debug in an initialized pipeline. NOT for surface mapping. NOT for spec generation (doc-this-writer). NOT for technical-debt analysis.

Second agent in doc-this Discovery pipeline (analysis). STRICTLY DESCRIPTIVE — describes code, never proposes improvements. Uses LSP for deterministic symbol inventory when available; falls back to Understand-Anything or direct reading. Per module: control flow, algorithms, data structures, metadata. Reads EVERY source file per module (markup, SQL, scripts — Total Source Coverage); token pressure checkpoints and resumes, never skips; large codebases may fan out reading to ≤3 Sonnet readers under explicit consent (verified before the ledger records). Generates code-analysis.md, per-module data-dictionary/[module].md + flowcharts/[module].md (Mermaid), modules.json. Binary confidence: 🟢 (file:line) or 🔴 (gap). No 🟡. Dispatched by doc-this after Scout — never auto-triggered by user phrasing; direct '/doc-this-code-analyst' is for resume/debug. NOT for surface mapping (doc-this-scout). NOT for business-rule interpretation (doc-this-detective). NOT for cross-module synthesis (doc-this-architect).

Use as an optional Discovery agent that documents the legacy database completely — tables, columns, relationships, constraints, indexes, AND the DB-resident business logic legacy systems hide: views, stored procedures, functions, triggers, rules, computed columns, non-trivial DEFAULTs, DB-side scheduled jobs (pg_cron, SQL Server Agent). Branches on database_ownership: owned → schema + business-logic + migrations-timeline docs; external → external-contract.md treating consumed objects as frozen interfaces, emits kind:database entries with visibility:external_dependency for Architect's external-surface.json; mixed → both with per-object ownership; none → skipped. Branches on schema_versioning: in-repo, external, unversioned (snapshot if available else 🔴 GAP), unknown. Profiles actual data (enum values vs code, null rates, orphans, rows-per-state) into data-profile.md when read access exists. Triggers: '/doc-this-data-master', 'analyze database', 'extract DB logic'. NOT a generic SQL formatter.

Use as an optional Discovery agent that extracts design tokens from CSS/SCSS/LESS variables, Tailwind config, UI library themes (MUI createTheme, Chakra extendTheme, Mantine, Ant Design), styled-components/Emotion theme objects, Style Dictionary tokens.json, design-tokens.yaml, Storybook stories, and screenshots. Documents color palette (primary/secondary/neutral/feedback with full scale and hex/rgb/hsl values), typography (font families with fallbacks, scale, weights, line-height, hierarchy), spacing/grid/breakpoints, other tokens (border-radius, shadows, z-index, transitions, opacity), and the in-house component library when one exists. Triggers: '/doc-this-design-system', 'extract design tokens', 'document UI design', dispatched by doc-this when frontend has a design system. NOT for design generation (use frontend-design plugin). NOT for screen-by-screen UI documentation (doc-this-visor).

Third agent in doc-this Discovery pipeline (evidence-consolidation). STRICTLY DESCRIPTIVE — extracts cited business rules, decision traces from explicit sources, state machines, RBAC/ACL matrices. Uses LSP (incomingCalls, findReferences, goToImplementation) for deterministic API classification when available; falls back to Understand-Anything call-graph or heuristics. Classifies endpoints public/private in external-surface.json. Cross-references DB-resident logic from Data Master. Confidence binary: 🟢 (cited) / 🔴 (gap). Outputs domain.md, state-machines.md, permissions.md, decision-traces/. Dispatched programmatically by doc-this after the Code Analyst — never auto-triggered by user phrasing; direct '/doc-this-detective' is for resume/debug in an initialized pipeline. NOT for surface mapping. NOT for C4 synthesis (doc-this-architect). NOT for proposing improvements or labelling bugs.

Use to get an analogy-driven explanation of every doc-this agent and when to use each. Covers all 12 Discovery agents with one-paragraph analogies (Scout = real-estate broker doing a walkthrough; Detective = Sherlock interpreting clues; Architect = cartographer producing formal maps; Reviewer = auditor stress-testing the contracts) plus the recommended sequence and customer-project safety notes. Triggers: '/doc-this-help', 'explain doc-this agents', 'which agent should I use for X', 'what does [agent] do'. NOT for actually running an agent — invoke that agent directly. NOT for the doc-this orchestrator (use it directly).

Use to stage doc-this Discovery output (.doc-this-sdd/) into the project's tracked SDLC chain — the single bridge and the only doc-this skill that touches docs/. Assigns next FR/NFR/ADR IDs (flat and compound), stamps OKF frontmatter (id/type/status/description + adrs/specs relation keys) on every promoted doc, writes docs/requirements/FR-NNN-[slug].md + ADR files, bootstraps docs/okf.yaml in legacy repos, regenerates index.md catalogs by dispatching okf-maintain and appends curated TRACEABILITY rows, generates ATDD 4-layer scaffolding (.feature files tagged @api/@browser/@database/@cli into the auto-detected runner — Reqnroll/Cucumber.js/playwright-bdd/behave/godog/cucumber-rs — plus DSL stubs and protocol-driver interfaces), prints a docs(FR-NNN) commit message, halts on collisions. Triggers: '/doc-this-promote', 'promote specs to docs', 'move the discovery output into docs', 'stage SDLC artifacts'. NOT for generation (doc-this-writer). NOT for review (doc-this-reviewer).

Sixth agent in the doc-this pipeline (review). Enforces describe-only pact — REJECTS pact violations. Validates 3 canonical files per unit, reclassifies confidence under binary 🟢/🔴, REJECTS 🟡/judgment phrasing/fabricated ADRs/technical-debt/NFRs-without-contract/bug-labels. Enforces ATDD discipline: public endpoint @api coverage, UI @browser coverage, private transitive coverage, cross-layer pairing, externally observable language. Validates citation quality (no UA paths or LSP operations as citations). Validates DB coverage for external/mixed, schema-version gate. Hard-REJECTs coverage failures (ledger⊉manifest, sampling phrases, grouped ui entries); spot-checks 🔴 gaps for answers in unread files. Generates confidence-report.md and questions.md. Dispatched programmatically by doc-this after Writer — never auto-triggered by user phrasing; direct '/doc-this-reviewer' is for resume/debug in an active pipeline. NOT for SDLC promotion (doc-this-promote). NOT for re-generation (doc-this-writer).

Use as the first agent in the doc-this Discovery pipeline (reconnaissance phase). Maps the surface of a legacy codebase: folder structure, languages and frameworks via config files (package.json, pom.xml, go.mod, Cargo.toml, *.csproj), dependency versions, package managers, application entry points, CI/CD configs, Dockerfiles, shallow database hints (Data Master goes deeper), test frameworks, and produces an organization-suggestion (module / use-case / endpoint / hybrid / feature) with rationale. Outputs .doc-this-sdd/inventory.md, dependencies.md, .doc-this/context/surface.json + file-manifest.json (Total Source Coverage ground truth) consumed by every downstream agent. Dispatched programmatically by doc-this after the first-run handshake — never auto-triggered by user phrasing; direct '/doc-this-scout' is for resume/debug in an initialized pipeline. NOT for deep per-module analysis (that's doc-this-code-analyst). NOT for database schema extraction (that's doc-this-data-master).

Use as an optional Discovery agent that resolves 🔴 gaps via dynamic analysis when static analysis falls short. STRICTLY DESCRIPTIVE — cites log lines / span IDs / samples; never proposes fixes or labels behavior as wrong. Read-only — never executes mutating code. Sources: log files, distributed traces (OTLP, Jaeger, Datadog), anonymized production samples, error-tracker exports (Sentry, Bugsnag, Rollbar). Resolves gaps like actual state machines, caller payloads, dead endpoints, error rates. Also runs the 🟢 corroboration sweep: stamps Evidence provenance (static → static + runtime, artifact-cited) on telemetry-matched scenarios — hard-advisory when the legacy system cannot be run live. Updates .doc-this-sdd/dynamic.md; promotes 🔴→🟢 ONLY on a cited specific runtime artifact — otherwise the gap stays 🔴. No 🟡. Triggers: '/doc-this-tracer', 'analyze logs', 'mine traces'. NOT for live system probing or load testing. NOT for static-only analysis (doc-this-code-analyst/detective).

Open a local viewer to browse doc-this output in a browser — navigate units (requirements/design/tasks), the external-surface catalog, C4/ERD/flowchart diagrams, coverage, and open gaps from the rich .doc-this-sdd/ staging tree, plus promoted SDLC docs (FR-NNN requirements, ADRs, TRACEABILITY, .feature specs) when present. Runs a co-located launch.mjs that builds a manifest and starts a localhost-only static server for a prebuilt Svelte app, then opens the browser; stop it with launch.mjs --stop. Triggers: 'view doc-this docs', 'open the documentation viewer', 'browse doc-this output', 'serve the docs', 'open .doc-this-sdd in a browser', '/doc-this-viewer'. NOT for generating docs — that's /doc-this. NOT for staging specs into docs/ — that's /doc-this-promote. NOT for UI screenshot extraction — that's doc-this-visor.

Use as an optional Discovery agent that documents the legacy system's UI from screenshots — without needing the system running. Extracts components (forms with field types/validations, tables with columns/actions/pagination, navigation menus and breadcrumbs), per-screen states (loading/empty/filled/error/confirm), navigation flow between screens, and writes one screens.md per unit plus globals (ui/inventory.md, ui/flow.md). Maps each screen to a unit per the project's [specs].granularity (module/use-case/endpoint/hybrid/feature/custom), creating empty unit folders ahead of Writer when needed (Writer respects existing folders). Saves original screenshots into [unit]/screenshots/ — never overwrites; same-name uploads get numeric suffixes. Triggers: '/doc-this-visor', 'document UI from screenshots', 'extract screens', dispatched by doc-this when the system has a UI and the user can supply screenshots. NOT for live UI scraping (use Playwright for that). NOT for design-token extraction (doc-this-design-system).

Fifth agent in the doc-this Discovery pipeline (generation). STRICTLY DESCRIPTIVE — turns accumulated cited evidence into folder-per-unit operational specs; never invents requirements. Units get requirements/design/tasks.md plus doc_level optionals. Specs are ATDD-ready: requirements.md catalogs every external surface the unit exposes, with Given/When/Then scenarios per public surface tagged @api/@browser/@cli/@message/@database and file:line cites. Binary 🟢/🔴 confidence; no 🟡. NFRs ONLY from a written non-functional contract — code patterns are NOT NFR evidence. Private endpoints get no @api (covered transitively via @browser). Generates code-spec-matrix.md from the manifest (row per source file); halts when a unit's UI page lacks read markup. Dispatched programmatically by doc-this after Architect+Detective — never auto-triggered by user phrasing; direct '/doc-this-writer' is for resume/debug in an active pipeline. NOT for SDLC promotion (doc-this-promote). NOT for review (doc-this-reviewer).