/document-this

Overview

Generates documentation across three audiences from one codebase:

• Non-technical readers — what the system does, in plain English, organized as user workflows backed by tests
• Developers — where things are, how they're structured, what patterns are in play
• AI agents — fastest path to useful context: entry points, test coverage map, known gaps, glossary

Scripts handle everything deterministic (directory structure, entity listing, test categorization). The agent handles everything that requires interpretation (prose, pattern recognition, workflow narratives).

Invocation

/document-this                              # Full project documentation
/document-this <file-path>                  # Targeted update of affected sections only
/document-this --focus "<Feature Name>"     # Deep-dive docs for a feature/subsystem into a named subfolder
/document-this --focus "<Feature Name>" <file-path>   # Targeted update within a focus subfolder

The feature name is what the user types (typically Title Case, often with spaces — e.g., "Materials Management", "Billing", "Stripe Webhooks"). The subfolder name is a kebab-case slug derived from that name (materials-management/, billing/, stripe-webhooks/) — never the human-readable name verbatim. The slug may also be a simpler form of the feature name when one reads more naturally (Materials Management → materials/).

Output

Default — full project documentation

generated-docs/
├── README.md               # Navigation hub: project summary + links to all docs
├── workflows.md            # Non-technical: user-facing workflows from system/integration tests
├── architecture.md         # Developer: stack, directory map, data model, patterns & conventions
├── ai-orientation.md       # AI agents: entry points, coverage map, known gaps, glossary
└── diagrams/
    ├── data-model.mmd      # Key entities + relationships (Mermaid erDiagram)
    └── architecture.mmd    # High-level component/module map (Mermaid graph TD)

--focus — feature/subsystem deep dive

generated-docs/
└── <slug>/                                 # Kebab-case slug of the feature name
    ├── workflows.md                        # Non-technical: workflows scoped to this feature
    ├── architecture.md                     # Developer: architecture scoped to this feature
    └── diagrams/
        ├── <slug>-architecture.mmd         # Same slug as the folder, kept as prefix for global uniqueness
        └── <slug>-data-model.mmd

Example: /document-this --focus "Materials Management" produces generated-docs/materials/ (or materials-management/ — see slug rules below) containing workflows.md, architecture.md, and diagrams/materials-architecture.mmd + diagrams/materials-data-model.mmd.

Focus mode produces only the four files above — no README.md or ai-orientation.md inside the subfolder. The top-level docs serve those roles for the whole project; the focus subfolder is a deep dive linked from them.

<slug> is a short kebab-case form of the feature name, used for both the folder and the diagram file prefixes:

• Default: kebab-case of the full feature name (Materials Management → materials-management).
• Shorter natural form is fine when one reads better (Materials Management → materials, Stripe Webhooks → stripe-webhooks or stripe). Use judgment.
• The same slug applies to the folder and to both diagram-file prefixes — they always match.

Multiple focus subfolders can coexist (generated-docs/materials/, generated-docs/billing/, etc.). Each is independent — regenerating one does not touch the others.

Regenerating any mode overwrites only the files it produces. Use git diff generated-docs/ to review.

If generated-docs/ does not exist, create it.

Scripts

All scripts live under scripts/ in this skill and emit JSON on stdout. Invoke them with node from the project root:

Invocation from project root:

Replace skills/document-this/ below with the path to this skill in your installation (for example, under .claude/skills/, .github/skills/, or .rolemodel-skills/skills/).

node skills/document-this/scripts/fingerprint.mjs
node skills/document-this/scripts/front_matter.mjs
node skills/document-this/scripts/directory_tree.mjs --depth 3
node skills/document-this/scripts/tech_stack.mjs
node skills/document-this/scripts/test_inventory.mjs
node skills/document-this/scripts/entities.mjs
node skills/document-this/scripts/entry_points.mjs

Fallback rule: if node is not available on PATH, do not error — fall back to agent-driven extraction using Read, Glob, and Grep for the same purposes. Scripts are an optimization, not a hard dependency.

Templates

Under templates/. Each is a markdown scaffold with {{PLACEHOLDER}} tokens the agent fills:

• README.template.md — navigation hub linking all generated files. Supports an optional {{FOCUS_SUBFOLDERS}} block for listing any --focus deep-dive subfolders.
• workflows.template.md — top-level scaffold for workflows.md.
• workflow-entry.template.md — one per workflow in the Workflows section.
• architecture.template.md — the Architecture section with explicit placeholders for stack, directory map, data model, patterns, optional JS architecture, and diagrams.
• ai-orientation.template.md — entry points, test coverage map (well-tested / undertested split), known gaps, glossary.
• focus-workflows.template.md — scaffold for a feature-scoped workflows.md inside a --focus subfolder. Same workflow-entry shape as the full version, with feature-specific intro and back-links to the top-level docs.
• focus-architecture.template.md — scaffold for a feature-scoped architecture.md inside a --focus subfolder. Tighter than the full architecture template — no JS-architecture section unless the feature is itself a JS subsystem.

Generation Process (full)

Execute in this order. Each step's output informs the next. Each phase can stand alone — you don't need to complete all phases in one run.

Phase 1 — Project Fingerprint

Run the fingerprint and tree scripts to orient yourself:

node skills/document-this/scripts/fingerprint.mjs
node skills/document-this/scripts/directory_tree.mjs --depth 3

From the output, derive — do not assume:

• Language and framework
• Test framework and where tests live
• Database(s) in use
• Major areas of the codebase
• What domain the project is in

Also read the README if one was detected.

Phase 2 — Workflow Discovery → workflows.md

Goal: Document every user-facing workflow in plain English, for a non-technical reader.

Discovery mechanism: Start from system/end-to-end and integration tests, not routes or controllers. Tests are human-authored descriptions of complete user interactions.

node skills/document-this/scripts/test_inventory.mjs

Then:

1. Read each system/integration test file to identify workflows
2. Trace into source code only as needed to fill in details tests don't make explicit (validation rules, supported formats, role-based access)
3. Write each workflow using templates/workflow-entry.template.md
4. Group workflows logically by role or feature area
5. For 2–3 headline workflows (highest centrality or test count), add an inline sequenceDiagram mermaid block

Persona filter: Write as if the reader is a non-technical manager or end user. Do not assume they know what "modal", "CRUD", or "API" means.

Inclusion rule: Only document a workflow if backed by at least one system or integration test. If a workflow appears in code but has no test coverage, note it in Known Gaps instead.

No-tests case: if the project has zero system and integration tests, put a prominent note at the top of workflows.md using the {{#if NO_SYSTEM_TESTS}} block in the template.

Phase 3 — Architecture Analysis → architecture.md + diagrams/

Goal: Give a developer enough orientation to understand the codebase in under 5 minutes.

node skills/document-this/scripts/tech_stack.mjs
node skills/document-this/scripts/directory_tree.mjs --depth 3
node skills/document-this/scripts/entities.mjs
node skills/document-this/scripts/entry_points.mjs

Cover these five things — keep each concise (not exhaustive documentation, just orientation):

1. Stack & key dependencies — language, framework, database, notable libraries worth knowing
2. Directory map — what lives where and why, one sentence per major folder
3. Data model summary — key entities and their relationships; do not enumerate every field
4. Patterns & conventions — e.g. "business logic lives in service objects", "controllers stay thin"
5. JavaScript architecture (optional) — include only if the project has significant JS: React/Vue/Angular component structure, state management, Stimulus or Alpine controllers, build/chunk strategy, Node.js services. Derive this from Glob/Grep — look for components/, controllers/, src/, etc.

Then create the Mermaid diagram files:

• diagrams/data-model.mmd — entity relationships (erDiagram syntax), derived from entities.mjs output and schema files. Include entity names and relationships only — do not add attribute rows to the tables.
• diagrams/architecture.mmd — high-level module/layer map (graph TD syntax), derived from entry_points.mjs and directory tree

Phase 4 — AI Orientation → ai-orientation.md

Goal: Give an agent the fastest possible path to useful context without duplicating what's in architecture.md.

Open with:

For stack, directory structure, data model, and conventions — see Architecture.

Then include exactly these four things:

1. Entry points map — for each major area of the codebase, the single best file to start reading (use entry_points.mjs output)
2. Test coverage map — split into "use tests as ground truth in" vs "read implementation code directly for" (derived from Phase 2 decisions and test_inventory.mjs)
3. Known Gaps & Uncertainties — things that couldn't be determined confidently during generation. Flag explicitly so future agents or developers know where to dig
4. Terminology / Glossary — project-specific terms, domain language, abbreviations, non-obvious naming conventions

Phase 5 — README → README.md

Write a brief navigation document:

• One paragraph: what the project is and who uses it
• Links to workflows.md, architecture.md, ai-orientation.md, and the diagrams
• A Deep dives block listing any existing --focus subfolders (one bullet per subfolder, linking to its workflows.md and architecture.md). If there are none, omit the block. Detect them by ls generated-docs/*/ for any folder that contains a workflows.md.
• Generation timestamp and auto-generated warning (use templates/README.template.md)

Focused Generation Process: /document-this --focus "<Feature Name>"

Use when the user wants deep documentation for a single feature or subsystem — typically because the top-level workflows.md and architecture.md only give it a paragraph of treatment and the feature is complex enough to warrant its own pair of files.

The output is a self-contained subfolder under generated-docs/<slug>/ with workflows.md, architecture.md, and diagrams/<slug>-{architecture,data-model}.mmd. Do not create a README.md or ai-orientation.md inside the subfolder.

Phase F1 — Feature scoping

Before reading or writing anything, identify what code, tests, models, controllers, JS modules, jobs, and config files belong to this feature. The agent does this — there is no deterministic script for "is this file part of the materials feature." Use whatever combination of these signals is appropriate:

• Name match — Glob for files with the feature name or its slug in the path (**/*materials*, **/*billing*).
• Reference match — Grep for class names, table names, or domain terms associated with the feature (MaterialList, MaterialsMemento, material_list_policy, …).
• Test inventory filter — re-run test_inventory.mjs and keep only specs whose names or paths match the feature.
• Cross-references — once you have an initial set, scan their imports/associations to pull in tightly coupled files (e.g., the strategy hook _patchMaterialMementosForCatalog belongs to the materials feature even though SystemStrategy.js doesn't).

Record the scoping set as you go — you will reference it across phases. Aim for the minimum set that explains the feature end-to-end, not every file that mentions it. If a file is only tangentially related, leave it out and rely on the top-level docs to cover it.

If the scoping set is empty or trivially small (one or two files), stop and tell the user — the feature may not exist under that name, or it may already be adequately covered in the top-level docs.

Phase F2 — Workflow discovery (scoped) → <slug>/workflows.md

Same approach as the full-mode workflow discovery, but filter to the feature scope:

1. From test_inventory.mjs, keep system/integration tests whose paths or describe/context strings reference the feature.
2. Read those tests. Each user-visible behavior they exercise is a workflow candidate.
3. Also include workflows that aren't covered by tests but are clearly part of the feature (e.g., a developer CLI for ingesting partner data) — but mark them explicitly as not test-backed and link to whatever evidence does exist (a script, a hand-written doc, a code path).
4. Group by audience (e.g., "Org admins", "Developers", "Partner systems"). Open with a "Who interacts with this feature" section.
5. Use templates/focus-workflows.template.md. Use templates/workflow-entry.template.md for individual workflow entries.
6. Add an inline sequenceDiagram for the 1–3 most central workflows.
7. Path references back to the rest of the repo use ../ (e.g., [spec/system/material_lists_spec.rb](../spec/system/material_lists_spec.rb)).

Phase F3 — Architecture analysis (scoped) → <slug>/architecture.md + diagrams/

Cover only the slices that matter for the feature:

1. Stack — only the libraries that the feature actually uses (don't list every dependency).
2. Directory map — only the directories that hold the feature's code, with one line each on what each contributes to this feature.
3. Data model — the tables and in-memory entities specific to the feature, with key columns and the JSON shapes they carry.
4. Pipeline / flow — if the feature has a notable end-to-end pipeline (ingest, request lifecycle, build chain), describe it with an inline ASCII or Mermaid diagram. This is often the single most useful section.
5. Patterns & conventions — only feature-specific conventions (e.g., "memento patches are best-effort, not validated").
6. Mapping section (optional) — if the user's mental model differs from the code, include a "User concept → reality" table. Useful when documenting features the user has questions about.
7. Notable files — 5–15 file paths the developer will keep returning to.

Then write the two diagram files:

• diagrams/<slug>-data-model.mmd — entities and relationships for the feature only. May include in-memory types (e.g., MaterialSpecifierMemento), not just DB tables.
• diagrams/<slug>-architecture.mmd — the feature's end-to-end flow as a graph TD (sources → processing → destinations). Group with subgraph blocks by time/space boundary (build-time vs. runtime, web admin vs. background job, etc.).

Use templates/focus-architecture.template.md as the scaffold. Path references back to the rest of the repo use ../.

Phase F4 — Cross-link from the top-level docs (only if they exist)

After writing the focus subfolder, if generated-docs/README.md exists, check whether it lists this focus subfolder under "Deep dives". If not, add it. Do not regenerate the top-level workflows.md / architecture.md / ai-orientation.md as part of focus mode — if those need cross-references too, suggest the user run /document-this to refresh them.

If the top-level docs do not exist yet, the focus subfolder is the only output. The user can run /document-this later to generate the top level; that run will detect the focus subfolder and link to it from the README.

Slug derivation

The slug is used for the subfolder name and both diagram file prefixes — all three always match.

• Default: kebab-case of the feature name (Materials Management → materials-management, Billing → billing, Stripe Webhooks → stripe-webhooks).
• Shorter natural form is fine when the long form reads awkwardly (Materials Management → materials, Stripe Webhooks → stripe). Use judgment.
• Lowercase, ASCII letters, digits, and hyphens only. No spaces, no underscores, no capitals.
• If the slug would collide with an existing focus subfolder of a different feature, pick a different form rather than overwriting.

Targeted Update: /document-this <file-path>

When called with a path (and no --focus), do not regenerate the whole document. Instead:

1. Identify which sections the file is most likely to affect:

   • Test files → workflows.md + test coverage map in ai-orientation.md
   • Entity/model files → architecture.md (data model) + diagrams/data-model.mmd + possibly Terminology
   • Service/controller files → architecture.md (patterns) + possibly workflows.md
   • Config/dependency files → architecture.md (stack)
   • JavaScript/TypeScript files → architecture.md (JS Architecture section) + possibly diagrams/architecture.mmd

2. Re-run only the relevant scripts

3. Regenerate only the affected sections

4. Ripple check: After updating, scan other sections for cross-references or dependent content that is now stale. Update those too if needed.

5. Do not regenerate the entire document unless the file affects all sections.

With --focus: /document-this --focus "<Feature Name>" <file-path>

If --focus is also passed, restrict the update to the focus subfolder:

1. Confirm the file is in scope for the named feature. If not (the file has nothing to do with the focus subsystem), tell the user and stop — don't silently update unrelated docs.
2. Re-run only the relevant scripts, then regenerate the sections of generated-docs/<slug>/workflows.md or architecture.md (and/or the feature-prefixed diagrams) that the file affects.
3. Do not touch the top-level generated-docs/*.md files — those are out of scope for a focused update.
4. Same ripple-check rule applies within the focus subfolder.

Quality Rules

General

• Never invent workflows. Only document what is evidenced by tests or source code.
• Never duplicate content between sections. If something belongs in Architecture, reference it from AI Orientation rather than restating it.
• Plain English in Workflows. Save technical language for Architecture and AI Orientation.
• No system tests = say so. Note this prominently at the top of workflows.md. Do not fabricate workflows from routes or controllers alone.
• Keep Architecture scannable. Short paragraphs or brief lists — not walls of text.
• Flag uncertainty explicitly. Use Known Gaps rather than guessing.
• Don't assume framework. Derive everything from what you find in the project.
• When scripts disagree with disk, trust disk. Update Known Gaps with the discrepancy.

Focus mode specifics

• Scope discipline. A focus doc covers one feature. If a workflow or entity is only tangentially related, leave it to the top-level docs.
• No README, no ai-orientation in the subfolder. Those roles belong to the top-level docs. Producing them inside a focus subfolder creates duplication.
• Always link back to the top level. The first paragraph of each focus doc should link to the top-level workflows.md and/or architecture.md so a reader knows there's a broader context.
• Use ../ for paths to files outside the subfolder. Test specs, source files, and other top-level project files all need the parent-dir prefix.
• One slug per subfolder. The folder name and both diagram-file prefixes always match (materials/diagrams/materials-architecture.mmd + materials/diagrams/materials-data-model.mmd, not materials/diagrams/mat-architecture.mmd).
• Refuse to invent the feature. If feature scoping comes back near-empty, stop and tell the user — don't write a thin doc just to have produced something.