Documenting projects that don't document themselves

Someone asks what your project does. You point them at the README. The README says "a modern, scalable solution for..." and then lists installation steps that haven't worked since the last refactor. The technical decisions that shaped the architecture are in someone's head — or in a Slack thread from eight months ago. The business case that justified the project is in a pitch deck that nobody can find.

This is the normal state of project documentation. Not because anyone is lazy, but because documentation is a second-class task. You write code, ship features, fix bugs, and document when there's time. There's never time.

The problem is scope

Documentation isn't one thing. It's at least twelve things, and they serve different audiences:

A project overview tells a new team member what this thing is. A technical specification tells an architect how the pieces connect. A business benefits analysis tells a stakeholder why it matters. An innovation themes report tells a technology leader what's novel about the approach. A features inventory tells a product manager what exists. An extensibility analysis tells a developer what can be built on top. A work zone map tells a team lead where development activity is concentrated. A technical readiness assessment tells an ops team whether it's production-ready.

And if you're maintaining multiple projects, you also need to understand how they relate — shared patterns, complementary capabilities, divergent approaches, portfolio-level themes.

No one writes all of this. So no one has all of it. And every decision made without it is a decision made on partial information.

Twelve reports from a single scan

The /doc-suite-generator pipeline scans a codebase once and produces twelve numbered reports plus a standardized README:

graph TD
    A["/doc-suite-generator"] --> B["project-scanner"]
    B --> C["readme-standardizer"]
    C --> D1["02 Project Overview"]
    D1 --> D2["03 Technical Spec"]
    D2 --> D3["04 Business Benefits"]
    D3 --> D4["05 Innovation Themes"]
    D4 --> D5["06 Features"]
    D5 --> D6["07 Extensibility"]
    D6 --> D7["08 Work Zones"]
    D7 --> D8["09 Portfolio Position"]
    D8 --> D9["10 Technical Readiness"]
    D9 --> D10["11 Worksona Themes"]
    D10 --> D11["12 First Principles"]
    D11 --> E["README Enrichment Pass"]
    E --> F["01 Executive Summary"]

Report 00 is the README itself — standardized with badges, getting-started instructions that actually work, a tech stack table, and a state-of-development assessment. This gets written first and updated after the rest of the reports enrich it.

Reports 02–08 are the analytical core. Each one is produced by a specialist skill that examines the codebase through a different lens. The project overview (02) describes what it is. The technical spec (03) describes how it's built — APIs, data models, deployment, security architecture. Business benefits (04) translates code into value propositions. Innovation themes (05) finds what's technically novel. Features (06) inventories everything the project can do. Extensibility (07) maps growth points. Work zones (08) shows where development activity is concentrated.

Report 01 is the executive summary that ties the others together and serves as the index.

Report 09 is portfolio position — where this project sits relative to others. This only becomes meaningful in multi-project mode but gets generated anyway as a self-assessment.

Reports 10–12 are the principle alignment reports. Technical readiness (10) scores production maturity across ten engineering dimensions. Worksona themes (11) evaluates against leadership principles. Worksona first principles (12) evaluates against sixteen structural constraints. These three give you a scored, graded assessment of the project's health.

Portfolio mode

Run /doc-suite-generator against a single project and you get 13 reports. Run it against a directory containing multiple projects and you get 13 reports per project plus a portfolio synthesis:

Seven synthesis reports compare all projects across AI innovation patterns, technology themes, UX patterns, leadership runbook adherence, structural principle alignment, and cross-cutting patterns. The portfolio overview summarizes everything with an aggregate scorecard.

This is where the pipeline earns its keep on multi-project teams. The synthesis reports expose things that are invisible at the individual project level: shared dependencies that could be extracted into a library, divergent approaches to the same problem, UX patterns that are consistent or inconsistent across the portfolio, and the organization's overall "technology signature."

The README problem, specifically

Every project has a README. Most of them are wrong — stale instructions, missing sections, no indication of whether the project is actively maintained. The readme-standardizer skill fixes this by reading the existing README, preserving what's valuable, and filling the gaps from the scan results.

The standardized README has: badges (status, language, framework, license), a description, a last-updated timestamp, a state-of-development matrix (🟢🟡🔴 across dimensions), a tech stack table, a user experience narrative, getting-started instructions, a light technical spec, and resource links to the docs/ directory.

After the analytical reports are written, the README gets a second pass — enriched with business value insights, refined user experience descriptions, and cross-links to the new documentation.

When to run it

When starting a new project. Generate the docs early. They'll be sparse but the structure is there, and they'll fill in as the project grows.

When someone new joins. The twelve reports are the most honest onboarding document possible. Better than a wiki that's three versions behind.

Before a pitch or review. The business benefits, innovation themes, and portfolio position reports give you presentation-ready material grounded in what the code actually does — not what someone remembers it doing.

Quarterly, across the portfolio. The synthesis reports track how the portfolio evolves. Which projects are converging? Which are diverging? Where are the shared investments paying off?

---

Resources

Pipeline reference: /doc-suite-generator — 13 reports per project + 7 portfolio synthesis reports, 10 specialist skills.

Key skills in this pipeline:

• project-scanner — the codebase inventory that everything builds on
• readme-standardizer — standardized README with badges and getting-started
• technical-specification — formal tech spec
• business-benefit-analysis — value props, ROI, target users
• technical-readiness — production maturity scorecard

Related reading:

• 01. How to audit your codebase before it audits you — pair with documentation for a complete health picture
• 04. How defensible is your product, really? — moat audit builds on the doc suite

Download: Full toolkit (252KB) — all 16 commands, all 11 skills, installs in 30 seconds.

---

Part of the Claude Skills Library.