wiki

What this skill does

# Wiki generation

Read a repository, then produce a set of interconnected documentation pages that explain what the code does and how it fits together. The output is a `droid-wiki/` directory of markdown files, uploaded to Factory via `droid wiki-upload`.

## 1. Survey the repository

Before writing anything, build a mental model of the codebase. The survey has two passes: a structural scan and a deep code scan.

### Pass 1: Structural scan

Read these files (when they exist):

- `README.md`, `AGENTS.md`, `CONTRIBUTING.md` — project intent and conventions
- `package.json`, `Cargo.toml`, `go.mod`, `pyproject.toml` — dependencies and scripts
- `docs/` directory — existing documentation
- Entry points (`src/index.ts`, `main.go`, `app.py`, etc.) — how the application starts
- CI/CD config (`.github/workflows/`, `.gitlab-ci.yml`, `Jenkinsfile`, `azure-pipelines.yml`, etc.)
- Build tool config (`webpack.config.*`, `vite.config.*`, `Makefile`, `build/`, `Gulpfile.*`, etc.)
- Lint/quality config (`eslint.config.*`, custom lint plugins, `rustfmt.toml`, `.golangci.yml`, etc.)
- Directory listing of the project root and key subdirectories

Build a map of:

- **What the project does** — its purpose in one or two sentences
- **Major subsystems** — the main areas of the codebase (e.g., API layer, database models, CLI, frontend components)
- **Key data flows** — how data moves through the system (request → handler → database → response)
- **External dependencies** — databases, APIs, message queues, third-party services
- **Build and test commands** — how to build, test, and run the project

### Pass 2: Deep code scan

The structural scan catches what's visible from directory names and config files. The deep scan catches features, domains, and capabilities that are only visible in the code itself. Probe the codebase for signals that reveal topics the structural scan missed:

- Grep for feature flag names in constants files — each flag often represents a distinct capability worth documenting
- Scan frontend route definitions and page components — each route group is a user-facing feature
- Scan API endpoint groups — each controller or router file represents a domain area
- Look inside `src/features/`, `src/modules/`, `src/domains/`, or equivalent directories — the names and contents reveal product capabilities
- Scan for service classes, event handlers, and job/worker definitions — these reveal background systems
- Check for domain-specific directories that don't map to obvious top-level names

The goal is to discover the **complete list of topics** the wiki should cover. The structural scan gives you the skeleton; the deep scan fills in the muscle. A feature like "Analytics" might not have its own top-level directory but lives inside `src/features/analytics/` or is revealed by a set of feature flags and API endpoints.

### Exhaustive subsystem discovery

After both passes, walk every top-level source directory (and one level below) to check for subsystems you missed. For each directory that contains its own service, module, or feature, decide:

- **Tier 1** — core subsystems most contributors will encounter. Full dedicated page.
- **Tier 2** — important but specialized. Shorter dedicated page.
- **Tier 3** — niche or thin wrapper. A paragraph in an "Other subsystems" page with directory pointers.

Small repos may only need a few domain pages. Large repos should have as many as the codebase warrants. Do not cap arbitrarily — let the repo's actual structure determine coverage.

### Often-missed areas

After scanning the source tree, check for these commonly overlooked areas:

- **Custom lint/analysis rules** — plugins or config that enforce project-specific conventions
- **Automation workflows** — CI/CD, bots, scheduled jobs, code generation scripts
- **CLI or dev tools** — internal tools, scripts in `scripts/`, `tools/`, or `bin/`
- **Test infrastructure** — custom test frameworks, fixtures, or automation harnesses beyond standard test runners
- **Multi-language components** — if the repo has code in a second language (e.g., Rust CLI in a TypeScript project), document it

If any of these are non-trivial, they deserve coverage — either as their own page or as a section in a related page.

### Survey output

At the end of the survey, produce a **survey context document** — a compact summary that will be shared with sub-agents. This document should include:

- **Repo summary** — 3-5 sentences: what the project is, its tech stack, and high-level structure
- **Architecture overview** — major components and how they connect
- **Discovered topics** — the complete list of features, systems, apps, packages, and primitives found during both scan passes
- **Key patterns** — coding conventions, error handling patterns, testing patterns
- **Glossary seeds** — project-specific terms encountered during the scan
- **Directory-to-purpose map** — which source directories map to which topics

### Coverage cross-check

Before moving to planning, reconcile two independent topic sources to ensure nothing is missed:

**Source A: Discovered topics.** The topics found during Pass 1 (structural scan) and Pass 2 (deep code scan). These include cross-cutting features that don't map to a single directory (e.g., "LLM integration" spanning multiple packages, "authentication" touching frontend, backend, and CLI).

**Source B: Directory enumeration.** For each lens that applies to the repo, run `ls` on the corresponding source directories and list every subdirectory:

- For apps: list every directory under `apps/` (or the repo's equivalent)
- For packages: list every workspace package directory
- For features: list every subdirectory under the feature directory (e.g., `src/features/`, `packages/frontend/src/features/`, or wherever the repo organizes features)
- For systems: list the top-level source directories that contain service or module code

**Reconciliation:** Merge both lists. For every item on either list, decide:

1. **Wiki page** — the item becomes a planned page (or section within a page)
2. **Skip with reason** — the item is intentionally excluded, with a specific reason (e.g., "empty directory — 0 source files", "deprecated — only test fixtures remain", "thin wrapper — covered in parent package page", "internal tooling — 3 files, not worth a standalone page")

The discovered topics catch things that directories miss (cross-cutting concerns, emergent patterns). The directory enumeration catches things that discovery misses (features the agent didn't encounter in the files it read). Together they produce comprehensive coverage.

Silent omissions are not acceptable. If a source directory exists with non-trivial code and has no wiki topic, that's a gap that must be justified.

## 2. Plan the table of contents

Design a page tree before writing any prose. The wiki has three tiers of content: always-present pages, organizational lenses, and conditional sections.

### Always-present pages

These pages appear in every wiki, in this order:

1. `overview/` — introductory material grouped under one section
   - `index.md` — project overview: what it does, who uses it, quick links
   - `architecture.md` — system architecture with Mermaid diagrams
   - `getting-started.md` — prerequisites, install, build, test, run
   - `glossary.md` — project-specific terms and domain vocabulary
2. `by-the-numbers.md` — codebase statistics snapshot (see below)
3. `lore.md` — timeline and history of the codebase (see below)
4. `how-to-contribute/` — how to work in this codebase
   - `index.md` — work pickup, PR process, review expectations, definition of done
   - `development-workflow.md` — branch, code, test, PR, merge cycle
   - `testing.md` — frameworks, patterns, how to run, mock, and cover
   - `debugging.md` — logs, common errors, troubleshooting runbook
   - `patterns-and-conventions.md` — error handling, coding style, cross-cutting concerns
   - `tooling.md` — build system, linters, code generators, CI