code-reading

---
name: code-reading
description: Create, inspect, refresh, or synchronize a revision-pinned reading edition of a Git repository. Generate one rich HTML viewer for developer, QA, and architecture views while retaining Markdown QA and architecture documents under one reading/ directory in one dedicated worktree. Use when someone wants to read or learn an unfamiliar codebase, create a durable code-reading mirror, share walkthroughs with a team, audit test coverage by module, inspect staleness, or update an edition after source changes. Do not use for ordinary code review, bug diagnosis, implementation planning, or a short architecture summary.
metadata:
  version: "0.1.0"
license: MIT
---

# Code Reading

Maintain a removable reading edition of a repository. Put every generated artifact under `reading/` in one dedicated reading worktree. Never hand-edit or annotate source files. Keep the reading worktree's source snapshot byte-identical to the pinned source commit. The interactive viewer integrates developer, QA, and architecture views. Keep QA and architecture Markdown as durable compatibility artifacts until the user chooses to remove them.

Use only Git, Python, the repository's own tools, and whatever code-navigation facilities the current agent provides. Do not depend on a particular model, agent harness, or vendor-specific tool.

## Load the contracts

Before initializing, synchronizing, or removing an edition, read [references/edition-protocol.md](references/edition-protocol.md). Before generating artifacts, read the applicable specifications in [references/role-views.md](references/role-views.md) and [references/annotation-contract.md](references/annotation-contract.md). For the `read` role, also read and follow [references/developer-view.md](references/developer-view.md).

The default document roles are:

- **read** — `reading/index.html` plus `reading/models/<module-path>.json`: the Developer tab shows the module skeleton and a selected symbol's concrete mental model.
- **qa** — `reading/tests/<module-path>.md` plus `reading/qa-models/<module-path>.json`: the same source-unit page exposes test evidence and gaps in a QA tab while retaining Markdown.
- **architect** — `reading/ARCHITECTURE.md` plus `reading/architecture.json`: the Reading View selector exposes a repository-level Architecture view while retaining Markdown.

`<module-path>` retains the source extension. For example, `lib/parser.py` maps to `reading/models/lib/parser.py.json` for developers and `reading/tests/lib/parser.py.md` for QA. This prevents same-stem modules in different languages from colliding.

## Select the operation

Infer one operation from the request:

- **Initialize** — create the branch and reading worktree from an exact source commit, initialize the manifest, then generate the selected document roles.
- **Status** — compare the recorded commit with a requested source ref and report staleness without writing.
- **Sync** — advance an existing edition to a requested source commit and regenerate every affected document.
- **Refresh** — regenerate incomplete, mechanically outdated, or inadequate documents without changing the recorded source commit.

Status is read-only. Generated changes belong only in `reading/` and `.agentic-survivor/`. During Sync, source paths in the reading worktree may change only by materializing exact blobs from the target commit. Commit or push only when the user requests it or an established shared-edition workflow already authorizes it.

## Establish the edition

Resolve the source repository, source commit, reading branch, worktree path, role set, and repository-specific include/exclude patterns before changing Git state. Default to:

- branch: `agentic-survivor/reading`;
- worktree: a sibling named `<project>-reading`;
- roles: `read qa architect`.

Initialize bookkeeping with `scripts/reading_edition.py roles init`. The helper selects common source and configuration formats by default; use `--include` for unusual text modules and `--exclude` for repository-specific generated, vendored, fixture, snapshot, or build paths. It records selection decisions in `.agentic-survivor/manifest.json`.

Keep personal editions local by leaving the branch unpushed and optionally ignoring `reading/` and `.agentic-survivor/` through local Git excludes. For a shared edition, commit the folder on the reading branch. Do not create one worktree per reader role and do not nest a source mirror inside the active source checkout.

## Inspect before writing

Obey repository instructions. Prefer a repository-provided semantic index when one exists. Otherwise inspect the exact source blob, directly related tests, imports, called contracts, configuration, and useful runtime evidence.

Inventory the target revision. Classify tracked paths as selected, excluded, or explicitly unsupported. Record an unsupported selected module with a concrete reason; do not silently omit it. Process large repositories in bounded batches and keep unfinished documents marked incomplete.

## Generate and verify

Generate artifacts in role order: read, qa, then architect. Apply these evidence rules:

- Keep the developer model language-neutral. Language-specific parsers may supply evidence, but the viewer contract must not depend on one programming language.
- Treat tests as evidence only for what their assertions establish.
- Verify every architecture edge against code or runtime evidence.
- Label unsupported rationale as `INFERENCE` or `UNKNOWN`.
- Keep full test analysis in QA documents and only decisive examples in developer models.

For each developer module, write its developer JSON model. For enabled QA and architect roles, write the Markdown document and its viewer JSON from the same verified evidence. Run every applicable gate, then install or refresh the shared viewer. Do not generate a Markdown tutorial for the `read` role.

```bash
python3 <skill>/scripts/reading_edition.py quality --read-model <model.json> --source-file <module>
python3 <skill>/scripts/reading_edition.py quality --qa-model <qa-model.json> --source-file <module>
python3 <skill>/scripts/reading_edition.py quality --architecture-model <architecture.json>
python3 <skill>/scripts/reading_edition.py viewer --edition-root <reading-worktree>
python3 <skill>/scripts/reading_edition.py quality --tests-doc <doc> --source-file <module>
python3 <skill>/scripts/reading_edition.py quality --architecture <doc> --source-repo <repo> --source-ref <commit>
```

Mechanical checks are necessary but not sufficient. Open `reading/index.html` through a local HTTP server. Verify Architecture and at least one interface-heavy and one control-heavy source unit when available. Switch Developer → QA → Developer and confirm the selected symbol remains selected. Apply the standalone mental-model check in `references/annotation-contract.md`; vague category labels fail even when JSON validation passes.

After verification, use `record` to mark completed documents. Supply an unsupported TSV with `--unsupported` when necessary; each line must be `module-path<TAB>reason`.

## Synchronize incrementally

Run `status` first. Compare the manifest's source revision with the exact target commit and inspect the full name-status diff. Handle additions, modifications, renames, copies, type changes, and deletions.

Reuse a document only when its source blob is unchanged and its claims remain valid. For each affected module:

1. rewrite the developer reading model completely from the target source blob and rebuild the viewer manifest;
2. refresh both QA Markdown and its QA viewer model when either source or related tests changed;
3. refresh both architecture Markdown and its architecture viewer model, including affected edges and journeys;
4. verify the document set and record the target commit.

The helper automatically plans newly selected modules as incomplete, removes deleted modules from the manifest, invalidates architecture completion when the source revision changes, and reports documents written against older annotation contracts as outdated.

## Report accurately

Finish with the reading branch and worktree, exact source commit, enabled roles, complete/incomplete/outdated/unsupported/excluded counts, verification performed and failures, staleness relative to the requested ref, whether the edition is local or shared, and the exact next sync command or natural-language request.

Never claim that a reading edition replaces code review, automated tests, runtime evidence, or architectural judgment.