/doc-and-modernize

name: doc-and-modernize
description: >-
  Two related workflows for a locally-cloned codebase, in one skill.
  Documentation mode produces a single, comprehensive, verifiable architecture
  document primarily by reading files on disk (local-first) — use it whenever the user wants to
  understand, map, document, research, or onboard onto a codebase ("research
  this repo", "write up the architecture", "do an architecture deep dive",
  "document how this codebase works", "map the system design", "create an
  onboarding doc"). Modernization mode generates a
  phased plan to modernize, migrate, upgrade, or rewrite a legacy system
  ("modernize this", "plan the migration", "how would we rewrite this", "how do
  we get off this legacy stack"); if no architecture document exists yet it
  first runs Documentation mode, then continues straight through to the plan. It
  assumes the legacy stack may be dead, runs a time-boxed feasibility spike, and
  picks the highest achievable rung on a safety ladder instead of demanding a
  fully-green legacy CI gate up front.

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: layer | technology | evidence (file+line).
• Entry points (backend, frontend, CLI — whatever applies).
• **Commands & Verification Inventory** — a table of the canonical project

commands (`command | purpose | evidence`), verified against the task runner / manifests / CI config, not guessed. Cover build, run/serve, test (and how to run a single test), lint, format, and — where they exist — typecheck, end-to-end/smoke, contract, and any other gate commands, plus the CI workflow(s) that run them and on what trigger. **Also record whether CI is *enforced*** — i.e. whether any workflow is a **required status check / branch-protection rule** that actually blocks merges, versus one that merely runs — since that distinction is a manual, human-configured setting that Modernization mode must surface, not assume. Enforcement usually cannot be determined from the local checkout alone: ask the user, or ma