# Doc And Modernize > Two related workflows for a locally-cloned codebase, in one skill. Use this skill when 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. - Skill: `paulasilvatech/doc-and-modernize` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add paulasilvatech/doc-and-modernize` - Raw SKILL.md: https://api.skillmd.com/api/skills/paulasilvatech/doc-and-modernize/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Productivity - Author: paulasilvatech (https://skillmd.com/u/paulasilvatech) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/paulasilvatech/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. ## When to invoke - "Document this codebase architecture." - "Map this repository for onboarding." - "Modernize or migrate this legacy system." - "Create a phased upgrade plan from the current code." ## 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. ### Procedure 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://@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 mark it `[UNVERIFIED]` unless confirmed from an authoritative source (any remote lookup is a flagged last resort, per the local-first rule above). This inventory is the source of truth that downstream planning (Modernization mode) cites so its exit criteria are runnable, not aspirational. Detect these per-ecosystem (npm/yarn/ pnpm, `make`, `just`, `cargo`, `go`, `poetry`/`tox`/`nox`, `gradle`/`maven`, etc.) — do not assume a stack. Mark any command you could not verify `[UNVERIFIED]`. - Directory layout for each major area, with a one-line purpose per directory. - **Deployment & Runtime Surface** — a table of every place the language/runtime and backing-service versions are pinned *for running* the system (not just building it): container base images (`Dockerfile`/`Containerfile`, `docker-compose*` build contexts), CI runner images / `setup-*` versions, `engines`/`.nvmrc`/`.tool-versions`/`runtime.txt`, serverless/lambda runtimes, and stateful data-store image tags (DB/cache/broker/search). Cite each with file+line. This surface is what a later platform/runtime bump must move in lockstep — flag any drift between build-runtime and run-runtime here so it's visible before a modernization plan is written. - **EOL / dead-dependency scan** — call out frameworks, runtimes, base images, and libraries that are end-of-life, unmaintained, or removed in a likely target major (e.g. a framework whose next major renames namespaces or drops a component family). Mark each `[INFERRED]`/`[UNVERIFIED]` as appropriate. This is the raw material Modernization mode's feasibility spike and hazard red-team build on. - Data/storage layers, APIs, plugins/extensions, background jobs, CI/CD, testing. #### Part 2 — Context & ecosystem - Local checkout identity table (remote, branch, HEAD commit, version, license). - Repo-specific agent/contributor docs present, and what rules they encode. - Developer gotchas (test watch-mode defaults, slow builds, codegen-must-commit, pre-commit hooks) — each cited. - How this project relates to its broader ecosystem or sibling services, *as visible from disk* (build tags, optional linked repos, separately-deployable components). Don't import remote ecosystem trivia. #### Part 3 — Architectural blueprint - Tech-stack summary (can reference the Part 1 table). - C4-style diagrams as Mermaid: Level 1 system context, Level 2 containers, Level 3 a representative request/component lifecycle. - Layering and dependency rules (what may depend on what, and what enforces it). - Cross-cutting concerns table: auth, config, logging, metrics/tracing, secrets, error handling, feature flags — each with its location and evidence. - Inferred Architectural Decision Records (reconstructed from code + docs). - Governance & enforcement mechanisms (CI gates, codegen verification, CODEOWNERS, review gates, compatibility rules). - "How to add a feature" guide plus common pitfalls. #### Subsystem deep-dives Identify the 2-3 most complex or architecturally significant subsystems — the parts a new engineer would most struggle with, such as an evaluation/scheduling engine, a plugin loader pipeline, a state machine, or a rendering/migration framework. For each, add a dedicated subsection covering its internal structure, lifecycle or state machine, key types, and data flow, with local file+line citations and a small Mermaid diagram where it clarifies the flow. This is what separates a useful onboarding doc from a directory listing — spend real effort here. #### Confidence assessment A table of the major claim areas rated **High / Inferred / Unverified**, so a reader knows exactly which parts to trust outright and which to double-check. #### Footnotes — local file citations A list of the key local files the document relies on, each with a one-line note on what it establishes. ### Conventions that make the document trustworthy These are the habits that distinguish this skill's output from a generic overview. They matter because the document's entire value is that a reader can rely on it without re-deriving everything. - **Cite every non-obvious claim** to a local path, with a line number where it pins something specific (`pkg/server/server.go#L39-L41`). Relative paths from the repo root keep links clickable. - **Mark uncertainty honestly.** Use `[INFERRED]` for something you reasoned to but didn't see stated, and `[UNVERIFIED]` for something you're repeating but didn't confirm (e.g. a build-timing claim from a doc you didn't re-measure). Honest gaps are more useful than false confidence. - **Resolve contradictions, don't restate them.** If two sources disagree (say a version literal in code vs. the manifest), go read the code, decide the real answer, and label it `[Resolved contradiction]` with the explanation. Leaving a reader to puzzle over a conflict is a failure mode. - **Note compatibility and deploy-cadence rules** the repo enforces — separate FE/BE PRs, bidirectional storage compatibility, additive-only protobuf changes — because these are the rules a newcomer most easily breaks. - **Prefer precise counts over vague ones.** "73 service packages", "89 workflow files" (from a directory listing) reads as verified; "many services" reads as a guess. ### Scope control Keep the document grounded in the checkout. It's easy to drift outward into the project's wider ecosystem (related products, README marketing, satellite repos) — resist that unless it's visible on disk, and clearly label anything that comes from outside the local tree. The reader asked for *this codebase*, documented faithfully. ## Extended reference Additional detailed guidance was moved to [references/extended-guide.md](references/extended-guide.md) to keep this skill within the progressive-disclosure budget. ## Progressive disclosure and bundled resources At discovery time, only `name` and `description` are loaded. Read or execute bundled resources only when the current task needs them. - `references/extended-guide.md`: expanded documentation and modernization guidance. - `references/migration-hazards.md`: runtime, framework, data, and compatibility hazards. - `references/copilot-instructions.template.md`: optional instructions template when requested. ## Output template ```markdown ## Documentation and modernization result **Status:** documented | modernization plan created | blocked **Mode:** **Snapshot:** ``, ``, `` ### Deliverables - Architecture document: `` - Modernization plan: `` ### Key evidence | Claim area | Confidence | Evidence | | --- | --- | --- | | Tech stack | High | `` | ``` ## Quality gate - [ ] The document is grounded in the local checkout, not remote assumptions. - [ ] Repository identity includes redacted remote, branch, and HEAD commit. - [ ] Stack, commands, CI triggers, runtime pins, and deployment surface are cited to files. - [ ] CI enforcement is confirmed by an authoritative source or marked `[UNVERIFIED]`.