Doc And Modernize

---
name: doc-and-modernize
description: >-
  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.
---

<!-- Generated from harness/github-copilot/plugins/arch/skills/doc-and-modernize/SKILL.md by harness/claude-code/scripts/convert_from_copilot.py. Edit the source, not this file. -->

# 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://<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 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:** <Documentation | Modernization>
**Snapshot:** `<remote redacted>`, `<branch>`, `<HEAD commit>`

### Deliverables
- Architecture document: `<path or inline>`
- Modernization plan: `<path, inline, or n/a>`

### Key evidence
| Claim area | Confidence | Evidence |
| --- | --- | --- |
| Tech stack | High | `<file#line>` |
```

## 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]`.