Doc-And-Modernize

# Documentation & Modernization

Two complementary workflows for a repository the user already has checked out

locally, bundled as one skill:

- **Documentation mode** — produce one definitive, cited architecture document

from the code on disk. Ideal for onboarding, system-design maps, or as the

evidence base for a modernization effort.

- **Modernization mode** — turn that architecture into a phased, safety-laddered

plan to upgrade, migrate, or rewrite a legacy system.

Mode selection

- If the user wants to **understand, document, map, research, or onboard onto** a

codebase, run **Documentation mode**.

- If the user wants to **modernize, migrate, upgrade, or rewrite** a system, run

**Modernization mode**. Modernization mode is self-sufficient: if no

architecture document exists yet, it runs the **Documentation mode** workflow

first (in the same pass), then continues straight through to the plan.

When in doubt, produce the architecture document first — it is the audited

evidence base both modes rely on.

Documentation mode

Generate one definitive, cited architecture document for a repository the user

already has checked out locally. The goal is a writeup someone could hand to a

new engineer as their onboarding reference — broad enough to cover the whole

system, deep enough on the hard parts to be useful, and trustworthy because

every claim traces back to a file on disk.

Why local-first

Reading from the local checkout (not the GitHub API or the web) is the deliberate

**default**. It is faster, free, avoids rate limits, and — most importantly — it

describes *the exact code in front of you* rather than whatever `main` happens

to look like remotely. The one tradeoff is that remote-only facts (star counts,

full CI run history, sibling repos) aren't visible. That's fine: state those as

out-of-scope or mark them `[UNVERIFIED]` rather than guessing.

Local-first is not local-*never*-remote: a web/API lookup is a deliberate

**last-resort fallback**, reserved for a fact that genuinely cannot be determined

from disk and that materially matters to the document. When you do reach for it,

flag the result clearly (e.g. `[UNVERIFIED]` / sourced-remotely) so the reader

knows it didn't come from the checkout, and never let it become the easy path

that displaces reading the code on disk.

Workflow

1. **Establish identity first.** Run `git remote -v`, `git branch --show-current`,

and `git log -1` so the document is anchored to a specific remote, branch, and

commit. A reader must be able to tell which snapshot this describes. Remote

URLs can contain embedded credentials (e.g. `https://<token>@github.com/...`)

— **redact any credentials/tokens** from the URL before recording it in the

document.

2. **Detect, don't assume.** Read the real manifests (`go.mod`, `package.json`,

`Cargo.toml`, `pyproject.toml`, `pom.xml`, etc.), the `Makefile`/task runner,

CI config, and any repo-specific agent or contributor docs (`AGENTS.md`,

`CONTRIBUTING`, `README`, `docs/`). These are the source of truth for the tech

stack and commands — prefer them over your prior knowledge of the framework.

3. **Map breadth, then drill into depth.** First build the whole-repo map (the

three lenses below), then pick the 2-3 hardest subsystems and go deep on them.

4. **Verify as you go.** Open the files you cite. If you reference a line number,

you should have actually read that line. Unsupported claims are worse than

omissions here — the whole value of this document is that it can be trusted.

Output structure

Produce a **single Markdown file** with the sections below, in this order. Adapt

the headings to the actual project (a CLI tool has no "frontend" lens — fold that

slot into whatever matters for that repo), but keep the three-lens shape and the

verification discipline.

#### Part 1 — Whole-repo technical deep-dive

- What the repository is (one paragraph, cited to README).

- Tech-stack detection table: lay