wiki-doc
Verified3-level documentation protocol for LLM-assisted codebases. Builds and maintains a structured knowledge base (module index → function index → function docs) that any LLM agent can navigate with minimal context loading. Supports two pass types: doc-only passes (no source edits) and edit-enabled passes (small fixes surfaced during documentation, gated by an explicit suggest-approve-apply-verify-log protocol). Use this skill whenever the user wants to: create documentation for a codebase or module, build a knowledge base from code review sessions, set up structured docs that stay synchronized with source code, run a "salvage" documentation pass on existing reviewed code, maintain or refresh existing wiki-doc documentation after code edits, trace variable/argument relationships across modules, generate AST-based function indexes, or audit a module for duplicates and dead code before documenting it. Trigger phrases: "wiki-doc", "3-level docs", "function index", "salvage documentation", "Level 2 index", "Level 3 docs", "document this module", "create the variable map", "refresh line numbers", "audit this module before documenting", "edit-enabled doc pass".
Wiki Documentation Protocol — v1
A 3-level documentation system in which an LLM agent builds and maintains a persistent knowledge base for a codebase, structured around functions and their relationships. Updates propagate bottom-up from source code; the maintenance cost is near zero so the docs stay current. The human curates, verifies, and directs. The agent handles bookkeeping.
This protocol covers two distinct working modes:
- Doc-only pass: the agent reads source and writes documentation. Source files are not modified.
- Edit-enabled pass: the agent may apply small, clearly-safe source fixes (dead-code deletion, comment cleanup, unambiguous renames) that surface during the doc pass — gated by an explicit suggest → approve → apply → verify → log protocol. Larger fixes are out of scope and routed to a dedicated debug session.
Conceptual lineage: Karpathy's llm-wiki (persistent agent-maintained wiki), MemPalace (hierarchical retrieval for bounded-context agents), Obsidian (interlinked markdown).
Section 1 — Triggers and scope
When to use this skill
- A codebase needs documentation created after the fact (post-hoc or "salvage").
- An existing wiki-doc'd codebase needs maintenance after source edits.
- A code review surfaced knowledge worth preserving in structured form.
- A function/variable trace needs to span multiple modules with bounded context.
- Line numbers in the index drift from source and need an authoritative refresh.
- A module needs an upfront duplicate / dead-code audit before documentation begins.
When NOT to use this skill
- One-off code explanations or single-file overviews — write a comment or short doc.
- API reference generation from docstrings — use a dedicated tool (Sphinx, etc.).
- Code review itself — this skill consumes the output of code review, it doesn't perform it.
- Generating tests, lint configs, or build artifacts.
Two pass types
The skill supports both doc-only passes and edit-enabled passes. Doc-only is the default: source is read but never modified. Edit-enabled fires only when the human explicitly opts in for a session and only for fixes within the in-scope category defined in Section 8. Anything ambiguous defaults to doc-only.
Section 2 — Three-level architecture
Level 1 — Module Index (index.md)
Entry point. Catalogs modules with version, date, status. Staleness detector.
Read FIRST on every session.
│
├──▶ Level 2a — Function Index (per module)
│ Every function: name, AST-generated line number, scope, brief description,
│ call relationships, status. Working layer for most agent tasks.
│ Append-only changelog at bottom.
│
└──▶ Level 2b — Variable & Definition Map (per module)
Module-level variables, closure-scoped state, shared dicts, hidden
dependencies. Human-triggered creation. Class-section L2b template
supports class-instance state (Section 5.5).
│
▼
Level 3 — Function & Variable Documentation (per module)
Full per-function entries (scope, args, returns, description, upstream, downstream,
dev notes, last-edit footer). Variable entries use `### VAR:` heading prefix.
Appendices for high-density workflow tables (Section 6.6). Future Considerations
appendix for forward-looking content (Section 6.7).
Ground truth. Edits originate here and propagate upward.
Update propagation (bottom-up)
Source code edit
→ Level 3 updated (description, args, returns, dev notes, last-edit footer)
→ AST script runs → Level 2a/2b line numbers auto-refresh
→ Level 2a changelog gets one-line entry
→ Level 2b updated if shared variables affected
→ Level 1 last-updated date bumped, version incremented if applicable
Read paths
- Session start: Read Level 1 first; identify modules relevant to the current task; spot-check version/date consistency.
- Most tasks: Resolve at Level 2a (function lookup, call-chain tracing, cross-module workflow assembly).
- Deep dives: Sub-agent dispatched with specific function name(s) → reads matching Level 3 entry by heading → cross-references source. Never reads full Level 3 file.
- Variable trace: Read Level 2b for the relevant module; descend to Level 3 for full variable docs only when needed.
Section 3 — File structure & naming
Default layout
project_root/
├── index.md # Level 1
├── indexes/
│ ├── <module_name>.md # Level 2a — function index
│ ├── <module_name>_vars.md # Level 2b — variable map
│ └── ...
├── docs/
│ ├── <module_name>_docs.md # Level 3 (appendices at bottom)
│ └── ...
├── tools/
│ └── ast_index.py # AST extraction script (Section 21)
├── handoff/
│ ├── s1_dump_<module>_<date>.md # Salvage Phase S-1 output
│ ├── session_report.md # Active session report (Section 13)
│ ├── fixes_log.md # Edit-enabled fix history (Section 8)
│ ├── <module>_line_deltas.md # Cascade tracking (Section 9)
│ ├── <module>_deadcode.md # Dead-code findings (Section 8)
│ ├── <project>_skill_gaps.md # Protocol deferrals (Section 19)
│ └── ...
└── .claude/
└── wiki-doc.config.yaml # Project config (Section 4)
Naming conventions
- Level 2a function index:
<module_name>.md(no suffix). - Level 2b variable map:
<module_name>_vars.md. - Level 3 docs:
<module_name>_docs.md(singular_docs, distinguishes from L2a<module>.md). - Bug findings filed during doc pass:
<name>bug.md(e.g.,excepthookbug.md) — short identifier +bug.mdsuffix. Status banner at top:**Status:** OPEN | RESOLVED <date>. - Dead-code clusters:
<module>_deadcode.md, append-only, organized by cluster number.
Project-config overrides
All paths above are overridable via the project config (Section 4). The defaults are
recommendations — a project may relocate handoff/ to docs/internal/, rename
indexes/ to index/, etc. The skill reads the config at session start; nothing in this
file is hard-coded as a path.
Section 4 — Configuration surface
Why a config file
Project-stable decisions live in a versioned file in the project, not in the agent's session memory. This way: (a) any agent reading the project sees the same config, (b) decisions survive across sessions and machines, (c) humans can audit and edit the file directly, (d) the file travels with the project (Git, sync).
File location
Default path: .claude/wiki-doc.config.yaml at project root. Overridable via the
config_path environment variable or skill argument; if neither, the default is used.
YAML chosen for human-readable comments alongside structured keys — projects benefit from "we picked frozen because…" annotations next to the values.
Required vs optional fields
The shipped template (wiki-doc.config.template.yaml) marks each field as # REQUIRED
or # OPTIONAL with the default value or (no default — must be supplied) inline.
- Required fields must be present in the project config. If absent, the agent asks the user during session startup (batched in a single message), then writes the answers back to the config file with the user's approval.
- Optional fields fall back to skill defaults if absent.
Session-start behavior
- Agent reads the project config from the configured path.
- If the file is absent: assume defaults for all optional fields; ask the user for all required fields; write a starter config with the answers.
- If the file is present: load it; for each missing required field, ask in a single batched message; write answers back with approval.
- For enum fields (e.g.,
last_edit_range: frozen | auto_shift), use the multi-choice prompt mechanism if the host environment supports it; otherwise free-form ask. - Agent reports loaded config in one line at session start: e.g., "Loaded
.claude/wiki-doc.config.yaml— frozen Last-edit anchors, fixes_log athandoff/fixes_log.md, 2 required fields supplied this session and written back."
What the config controls
- Path conventions (handoff dir, fixes_log path, indexes dir, deadcode pattern, archive dir).
- Verification commands (pre-edit rule list, post-edit command list).
- Cascade policy (
last_edit_range, optionalfrozen_anchor_prefix). - Source-internal metadata (field names, format, bump rules).
- Style (appendix line threshold, depth-calibration knobs).
- Session report (suffix convention, archive path).
- Doc field labels for localization (e.g.,
description→說明).
See the shipped template for the full key list with descriptions and defaults.
Section 5 — Required fields per level
5.1 Level 1 — Module Index fields
| Field | Description |
|---|---|
| Module name | File name (e.g. mymodule.py) |
| Path | Relative path from project root |
| Brief description | One line — what this module does |
| Version | Version string from source (if present in file header) |
| Last-updated date (index) | When this index entry was last reviewed |
| Last-modified date (file) | From filesystem (stat or ls -l) |
| Level 2a path | Path to function index, or — if not yet created |
| Level 2b path | Path to variable map, or — if not yet created |
| Level 3 path | Path to function docs, or — if not yet created |
| Status | active / in-progress / archived / not-reviewed |
5.2 Level 2a — Function Index fields
| Field | Description |
|---|---|
| Function name | As defined in source |
| Line number | Auto-generated via AST — never manually maintained |
| Scope | Auto-detected by AST (top, cls:Class, cls:Class (in <method>), cl:<closure>, cl:<closure> (in <inner>)) |
| Brief description | One line |
| Status | documented / pending / stub / deleted |
| Last updated | Date of last Level 3 edit for this function |
The deleted status preserves a breadcrumb when a def is removed via Section 8 edits —
keeps the row in L2a so future readers don't ask "where did X go?" Treat deleted rows
as deprecated breadcrumbs: retain them across several version cycles (e.g., v1.0 →
v1.6) so users updating from older versions don't lose a needed reference. A periodic
cleanup pass purges them only after enough versions have shipped that downstream
readers won't be affected.
5.3 Level 2b — Variable Map fields
| Field | Description |
|---|---|
| Variable name | As used in source |
| Line number | Auto-generated via AST --vars (Section 15) |
| Defined at | Module-level / closure / class / unpacked from file |
| Type | Data type (if inferrable or documented) |
| Scope rule | global / nonlocal / local / closure |
| Owner | Function or scope that creates/initializes it |
| Readers | Functions that read this variable |
| Writers | Functions that modify this variable |
| Inter-module flow | If passed to/from other modules, which and how |
| Notes | Hidden dependencies, implicit contracts, gotchas |
5.4 Level 3 — Function entry minimum-fields template
Every L3 function entry has these fields. Fields with no content show the field name with
— rather than being omitted (skip-resistance: even an empty field is salient).
### function_name
**Scope:** [auto-detected scope tag]
**Arguments:**
- `arg_name` (type): description
- (or `none` for no-args)
**Returns:** type — description (or `None — side effect: [description]`)
**Description:**
[Concise prose: what it does, why it exists, non-obvious behavior. For high-density
functions, refer to the appendix instead of expanding here.]
**Upstream:**
- Line N — caller_function (intra-module) or caller_module.caller (inter-module)
- (or `—` if unused / entry-point)
**Downstream:**
- intra-module: helper_a, helper_b
- inter-module: other_module.fn_x
- (or `—` if leaf function)
**Dev notes:**
[Categorized — see Section 6.3. If no dev notes warranted: omit the field, do not pad.]
**Last edit:** YYYY-MM-DD — [one-line description; date frozen unless cascade policy
configured to auto_shift, in which case the line range below also shifts]
5.5 Class-section L2b template (External resource refs)
For classes (or class-bodied closures), L2b extends with a class-section using a 4-subsection structure. Subsections are optional — if a class has no resource refs, omit that subsection rather than padding it.
## Section <Letter> — `<ClassName>` instance state
### Construction params
[Fields populated from constructor arguments. Example: `flag_vars` (dict, set in __init__).]
### Lifecycle flags
[Boolean / state flags governing the instance's lifecycle. Example: `is_open` (bool, set
True in __init__, flipped False in close()).]
### Mutable state
[Containers and values mutated post-construction. Example: `samples` (list, appended by
add_sample, cleared by reset_samples).]
### External resource refs
[References to objects owned outside the class — Tk widgets, file handles, DB connections,
network sockets, threads. Note: in GUI projects this subsection often holds widget refs.
In services it may hold DB sessions or message queues.]
The "External resource refs" name generalizes the proven 4-subsection pattern beyond GUI-specific framings. GUI projects should still document widget refs here.
Section 6 — Writing calibrated entries
This section encodes the structural defenses against three common failure modes when an LLM writes documentation: hallucination (inventing behavior or contracts not in source), skip (omitting load-bearing detail), and drift / over-explanation (padding with restatement of code or training-data leakage).
6.1 Source-anchor every behavioral claim
Every dev note and every behavioral statement in a Description must source-anchor. Convention:
- Inline:
the gate diagnostics run after PPM computation (lines 8073-8133). - Or footer-style at end of dev note:
(line N)or(lines N-M).
If the agent cannot point at lines in the current source, it does not write the claim. This is the primary anti-hallucination defense.
6.2 Minimum-fields template (skip-resistance)
The minimum-fields template (Section 5.4) is non-optional. Every entry has scope,
arguments, returns, description, upstream, downstream, last-edit footer. Empty fields
show the field name with —, they are not omitted. A skip-prone model has to actively
delete a field-name to shortcut, which is more salient than just omitting content.
6.3 Dev-note eligibility — four categories that earn space
A dev note must fit one of these four categories. If it doesn't fit any, it does not belong in the entry.
- Regression anchor — date-stamped record of a prior bug and its fix. Format: "(fixed YYYY-MM-DD) Previously … . Now … . If a related case is reintroduced, check …" The date and prior-state description are both required.
- Footgun pin — "Don't refactor away because …" or "This looks redundant but …" Calls out behavior whose subtlety would otherwise be lost in a refactor.
- Load-bearing contract callout — interface assumption, type-dispatch shape,
tuple-order convention, multi-site coordination requirement. Example: "The
isinstance(w, tuple)chain in this function is mirrored in 3 other sites; changing the discriminator shape requires updating all 4." - Cross-module interface note — implicit contract with another module not visible from the call signature.
6.4 What does NOT belong in dev notes
- Forward-looking speculation ("In the future, schema versioning would help …", "If we later support …"). Goes to a per-module Future Considerations appendix (Section 6.7), not to per-function dev notes.
- Restatement of code as English — "First it iterates the dict, then for each key it …". The Description carries the prose-level summary; reiterating in dev notes is padding.
- Repeated cross-cutting concerns across siblings. If three sibling methods share a
bug or convention, document it once in the most discoverable entry and use
See also: <function>pointers in the others. Don't restate. - Training-data leakage — content the model "knows" about Python or libraries generally but isn't specific to this codebase.
6.5 Proportionality floor
Every L3 entry has a floor of approximately 15 lines (scope, arguments, returns, description, upstream, downstream optional, last-edit). Even trivial helpers get this much. The floor protects against skip; the eligibility rules above protect against bloat.
6.6 Appendix-split rule
When stage-by-stage detail would dominate an entry, split it: keep the L3 entry thin (orientation + dev notes + last-edit) and put the workflow table in an appendix at the bottom of the L3 file.
Trigger threshold: function body > ~100 lines OR > 5 distinct stages OR > 30 dev-notes
lines. The exact threshold is configurable (style.appendix_threshold_lines).
The L3 entry's Description references the appendix: See Appendix A-<function_name> for the stage-by-stage workflow.
Appendix table format:
## Appendix A-<function_name>
| Stage | Lines | Operation | Key Variables | Notes |
|-------|-------|-----------|---------------|-------|
| 1 | N-M | High-level operation | vars touched | Optional context |
| 1.1 | N-M | Sub-row detail | — | Per-line specifics |
Sub-rows (dotted numbering) optional, used when stage-level detail isn't enough.
6.7 Future Considerations appendix
A per-module appendix at the bottom of the L3 file, after function entries and workflow appendices. Format:
## Future Considerations
### Schema versioning
Currently `load_flags` doesn't check a schema version field. If config schema evolves
(field renames, type changes), a versioning mechanism would help. Filed in
`<project>_skill_gaps.md` if relevant.
### Encoding asymmetry on Windows
…
This is the home for forward-looking content evicted from per-function dev notes by rule 6.4. Keeps dev notes tight while preserving the speculation.
Section 7 — Salvage protocol
For codebases that need documentation created after the fact. Five phases (S-1 through S-5) plus checkpoint/resume.
Prerequisites
- The target module has been examined during code review (interactive exploration with the human).
- The agent has session memory of explanations discussed.
Phase S-1: Harvest review knowledge
Trigger: "Please save the explanations of functions we've explored during this code review session" (or equivalent).
The agent:
- Collects all function explanations discussed during the review.
- Outputs in structured format per function (one record):
**function_name** Summary: [one-line] Key points: [bullets of what was discussed] Args noted: [types/purposes mentioned] Relationships noted: [call chains traced] - Saves to
<handoff>/s1_dump_<module>_<date>.md. - Does NOT explore undiscussed functions — the human chose what to review.
Phase S-2: Scaffold structure
- Run
ast_index.pyon the module to get all function names + line numbers + auto-detected scope. - Create Level 2a with every function listed (name, line, scope).
- Functions from S-1 get descriptions pre-filled.
- Others get
description: —andstatus: pending. - Extract any existing docstrings or inline comments where present.
- Update Level 1: list this module with
status: in-progress.
Phase S-3: Pre-documentation audit
NEW phase. Runs after the L2a scaffold exists, before L3 drafting begins.
Trigger: explicit human request, or automatically scheduled by S-2 in projects that
opt in via audit.run_after_s2: true.
- Run
ast_index.py --auditon the module. - Outputs surfaced (each as a section in the audit report):
- Duplicate-name candidates: same function name in multiple scopes (outer/inner pairs, sibling shadows). Each pair flagged with both line numbers and a note about which scope captures which.
- Zero-caller candidates: defs with no observed call sites within the file. Note: this is intra-file only; cross-file zero-caller detection requires a separate pass.
- Shape anomalies: defs nested inside string literals or unreachable branches (heuristic; flagged for human review).
- Audit report saved to
<handoff>/<module>_audit_<date>.md. - Human reviews; for confirmed duplicates, plans paired-entry coverage in S-4 (document both, side-by-side compare, decide loser).
- Confirmed dead-code candidates filed to
<handoff>/<module>_deadcode.mdfor later resolution (Section 8 protocol if edit-enabled, otherwise tracking only).
The audit phase prevents the disruptive mid-S-4 discovery of duplicates that would otherwise force the agent to switch into compare-and-decide mode mid-pass.
Phase S-4: Systematic documentation (clean session)
Was Phase S-3 in v0.2 of the protocol.
Start a fresh session for L3 creation. Load the S-1 dump, L2a index, audit report (if S-3 ran), and source.
Ordering: Follow workflow order (natural data flow) for human readability. When a function calls an undocumented downstream function, document the leaf as a brief stub first, then return to the caller.
Per function:
- Agent drafts the L3 entry following Section 5.4 and Section 6 rules.
- Agent presents draft to user for review.
- User approves, edits externally (then notifies agent), or requests changes.
- If user edits related functions, they notify agent to update those entries.
- Agent marks function as
documentedin L2a.
Cross-module boundaries: Record cross-module calls as typed references (e.g., "calls
other_module.some_function"). Flag in L1 as dependency. Do NOT drill into the external
module — that's a separate salvage pass.
Edit-enabled mode (optional): If the human enabled edit-enabled mode for this
session, fixes surfaced during S-4 follow Section 8's protocol. Otherwise stay doc-only:
file findings to <name>bug.md for later resolution.
Phase S-5: Variable mapping (before finalization)
Was Phase S-4 in v0.2.
Trigger: "Please create the list and mapping of variables and arguments in this module."
- Read L2a to collect all referenced arguments/variables.
- Run
ast_index.py --varsfor module-level assignments. - Build L2b initial map.
- Hidden behavior sweep: Search for variable operations NOT captured by the function index — assignments in conditionals, values unpacked from files/configs, variables passed through closures without explicit parameters.
- Present unknowns to the user as a numbered list for resolution.
- Check session logs — hidden operations often surfaced during prior debugging.
- After user resolves all items: write L3 entries for key variables, finalize L2b.
- For class-bodied closures or class definitions, extend L2b with a class-section using the Section 5.5 template.
Checkpoint/Resume
Salvage sessions for large modules will exceed context limits.
- L2a tracks each function:
documented/pending/stub/deleted. - On mid-session end, write checkpoint at top of L2a:
**Salvage checkpoint:** Documented through `some_function`. Next: `next_function`. [date] - Next session reads checkpoint, resumes without re-reading completed entries.
- S-1 dump and variable summaries remain available across sessions.
Section 8 — Source edits during a doc pass (edit-enabled protocol)
This protocol fires only when the human has explicitly enabled source edits for a session. It governs the moment when a doc pass surfaces a fixable issue and the agent needs a defined sequence to apply the fix safely.
Scope
In scope (edit-enabled allowed during salvage):
- Dead-code deletion when a def has zero callers OR is shadowed by a clearly active def.
- Comment cleanup (rotted/stale comments).
- Single-line typo or rename, unambiguously broken.
- Insertion of a clearly-missing return statement when control-flow analysis confirms the absence is a bug, not intentional.
Out of scope (deferred to dedicated debug session):
- Bug fixes requiring behavior tracing or runtime monitoring.
- Bugs where consumer impact is unclear without a regression test.
- Refactors that change behavior, even subtly.
- Anything where the agent would benefit from more context than the doc pass provides.
When in doubt: file as <name>bug.md and continue the doc pass without applying. Filing
is always allowed; applying requires confidence.
Per-fix protocol (steps 1–5)
For each in-scope fix:
-
Pre-edit verification (agent, internal). Apply project-defined verification rules (config key:
verification.pre_edit_rules). Confirm line numbers, trace call chain, apply scope/interface checks. Surface in chat only if something surprises. -
Suggestion to human. Structured preview block:
**Fix:** <ticket-or-finding-name> **File:** <path> **Reasoning:** <one line + ticket reference> **Delete (lines N-M):**Context preserved (1-3 lines each side):
Comment to add: <none | proposed comment>
Comments are proposed only when the WHY is non-obvious from context. Default `none`. -
Approval gate. Human approves, questions, requests edits, or rejects. Sequential per fix (not batch) until the protocol is proven stable in the project; then projects may relax to batched approval.
-
Apply. Agent uses Edit tool on the source file with the approved change.
-
Defer file-wide post-edit scan. Do NOT run
verification.post_edit_commandsyet — that fires once per cluster (Section 12), not per edit.
End-of-cluster protocol (steps 6–9)
After all fixes in the cluster have been applied:
-
File-wide post-edit verification. Run all commands in
verification.post_edit_commands. For Python projects this typically includespython -m py_compile <module>, grep for orphaned method references, callback-def existence checks. Project-defined. -
Index cascade. Run AST script. Refresh L2a function-row line numbers, L2b variable line numbers (Section 9). Update L2a status fields for deleted defs (
deletedstatus, retain row). Delete corresponding L3 entries (L3 = current-state ground truth). Append L2a changelog entries. Update L1 last-updated date. -
Append to fixes log. One entry per fix:
## YYYY-MM-DD — <module>:<finding-name> **Files+lines:** <module>:N-M **Source delta:** -K lines (or +K, or rename) **Verification:** <commands run + outcome> **Ticket:** <name>bug.md → status banner updatedPath is
verification.fixes_log_path(typicallyhandoff/fixes_log.md). -
Bisect rollback if verification fails. If post-edit verification (step 6) fails, bisect by reverting fixes in reverse application order. Re-run verification after each revert until clean.
Index handling for deletions
- L2a row: retain, flip
status: deleted, brief one-line note pointing at the fix-log entry. - L3 entry: delete entirely. L3 represents current-state ground truth; stranded "DELETED" entries are clutter. The L2a row carries the breadcrumb.
- Bug file: add
**Status:** RESOLVED YYYY-MM-DD (see fixes_log.md)banner at top. Original discovery content preserved below.
Duplicate / dead-code handling
For duplicates surfaced by Phase S-3 audit (or discovered mid-pass):
- Document both copies in L3 first, each flagged with link to deadcode tracking.
- At the seam (end of cluster batch where the pair was documented), present side-by-side compare to human.
- Human picks survivor; loser is queued for deletion via the per-fix protocol above.
- After deletion: cascade as in step 7.
For zero-caller dead code from S-3 audit: same protocol — document, flag, delete via per-fix protocol with audit findings as the ticket reference.
Sequence cadence default
Sequential approve+apply per fix is the default (one fix at a time). Reason: makes the protocol auditable and surfaces friction explicitly.
After the protocol is proven stable in a project (typically after several clean cluster seams), projects may opt into batched approval — agent presents all pending fixes in one block, human approves all at once, agent applies in order. This is a project-level decision, not a skill default.
Section 9 — Cascade management
Source edits shift line numbers. Some references auto-refresh via AST; others are prose-level and require manual review. This section defines what cascades and how.
What auto-refreshes vs. what doesn't
Auto-refreshes (via AST script):
- L2a function-row line numbers.
- L2b variable line numbers (via
--vars). - Module-level constant line numbers.
Does NOT auto-refresh — requires manual review or project-config policy:
- L3 prose line cites — explicit
(line N)and(lines N-M)references inside Description and Dev notes. - L3 "Last edit" footers —
source read of lines X-Y(depends oncascade_policy.last_edit_rangeconfig). - Frozen anchors used as historical breadcrumbs (depends on
cascade_policy.frozen_anchor_prefixconfig). - Cross-references in dev notes ("see line N", "callsite at line M").
- Line refs inside
<name>bug.mdand<module>_deadcode.mdfiles.
Per-cluster batched cascade
The cascade fires once per cluster of edits, at the cluster seam — not per individual edit. This is the cadence rule (Section 12). A single AST run, a single index pass, one changelog batch. If a cluster has only one edit, per-edit and per-cluster collapse.
Line-delta tracking artifact
For sessions with multiple edit-enabled fixes, a <module>_line_deltas.md artifact in
the handoff directory tracks cumulative source-line delta. The artifact is for human
audit and for agents reasoning about historical state — the agent does not apply
shifts from this table. The authoritative line numbers always come from a fresh AST run
on current source (Section 10). Format:
# <module> Line Delta Tracking
| Date | Cluster | Δ lines | Cumulative | First affected line | Notes |
|------|---------|---------|------------|---------------------|-------|
| 2026-04-28 | cluster 1 | -21 | -21 | 6776 | dead ML params API block |
| 2026-04-28 | cluster 3 | -6 | -27 | 6890 | inner _short_id duplicates |
| 2026-04-29 | cluster 4 | -11 | -38 | 4523 | _update_main_status_for_batch shadow |
The First affected line column is optional but recommended — it captures the cutoff
above which references are unaffected and below which they shift, useful for human
review of which docs might need re-reading after a series of edits. Recommended for
projects with active edit-enabled work; optional otherwise. Path and column set are
configurable.
Project-config policies
Two cascade decisions are project-configurable, no skill-mandated default for the more ambiguous one:
-
cascade_policy.last_edit_range(default:frozen):frozen—Last edit: source read of lines X-Ystays as the historical snapshot. The date stamps when it was read; line numbers don't shift on subsequent edits. Lower maintenance; archaeology-friendly.auto_shift— line range updates on every cascade to point at current source. Higher navigation utility; high maintenance cost.
-
cascade_policy.frozen_anchor_prefix(optional, no default):- If projects use prefix-tagged historical anchors (e.g.,
[[anchor:original-2026-04-25]]), declare the prefix here so the cascade tooling can distinguish historical-from-current anchors. If absent, all anchors are treated as current and shift on cascade.
- If projects use prefix-tagged historical anchors (e.g.,
L3 prose line-cite policy
Three options, project picks (default: status quo):
- Status quo (default): prose line cites are free-form text. Manual grep + human review on demand for staleness. Low cost per use; cost scales with how often refresh is invoked.
- Annotation convention (opt-in): wrap line cites in a parseable tag the AST tool
can detect and shift (e.g.,
[line:7711]or<sline n="7711"/>). Higher upfront cost; lower per-refresh cost. Recommended for projects with high refresh frequency. - Drop line cites entirely (opt-in): rely on function-name + scope identification in prose; never cite line numbers. Cleanest but loses navigation utility.
Configure via cascade_policy.l3_line_cite_handling: status_quo | annotation | dropped.
Section 10 — Reference Refresh (R-1)
On-demand line-number reconciliation. Callable from any mode (salvage edit-enabled passes use it per-cluster automatically; active maintenance uses it on-demand).
Trigger
- Human says "refresh line numbers" / "run reference refresh" / equivalent.
- Drift detected at session start: file mtime newer than L2a
last_updatedfield. Agent surfaces the gap and offers R-1.
Steps
- Agent (or sub-agent dispatched for read-only discovery) runs
ast_index.pyandast_index.py --varson current source. - Agent diffs AST output against L2a function-row line numbers and L2b variable line numbers.
- Agent reports drift in one structured message: "23 functions shifted, 4 vars shifted, 2 new defs, 1 def deleted."
- Per
cascade_policy.last_edit_range:- Frozen mode: L3 footers stay as-is. Refresh affects L2a + L2b only.
- Auto-shift mode: L3 footers updated to new ranges. Agent presents diff for approval before write.
- Optional add-on: human asks "also check L3 prose cites?" → agent greps L3 for line cites, reports candidates, human reviews per-case (no automation here — too risky for prose semantics).
- Agent writes updates after approval. L2a
last_updatedfield bumped. Cascade-style changelog entry appended.
Sub-agent dispatch (for context savings)
The discovery + diff phase (steps 1–3) is purely read-and-compute; offloading to a sub-agent saves main-agent context. The sub-agent returns the drift report. The main agent presents to human, gets approval, and writes. This preserves the read-only sub-agent contract (Section 18): sub-agents never apply updates.
L3 prose cite limitation
AST cannot see prose line cites. They remain human-review territory unless the project has opted into annotation convention (Section 9). Be honest about this limit when running R-1: report which checks are automatic and which are manual.
Section 11 — L2b extension trigger
For incremental L3 salvage where L2b already exists for a partial scope and new L3 entries introduce new variable readers/writers, two signals trigger L2b extension. Whichever fires first.
Signal 1: Per-cluster forward-pointer check
At the start of each cluster's L3 work, grep the existing L2b file for the cluster's
function names and explicit forward-pointer markers — strings like "will document when X gets L3" or <!-- L2B-TODO: -->. If markers exist for any function in the upcoming
cluster, plan L2b extension as part of the cluster.
Signal 2: End-of-cluster cross-check
After writing L3 entries for a cluster, scan each entry's scope-captured variables and arguments (closure constants, mutable state, module-level constants used by the function). Cross-reference against L2b. Anything cited in L3 that isn't in L2b → extend L2b in the same session.
Salvage / extension scope boundary
- In scope (during salvage): add rows for newly-referenced closure constants, closure mutable state, closure tk vars / DB sessions / etc., module-level constants. Update existing rows' Readers/Writers columns when the cluster introduces new readers/writers. Resolve TODO markers in L2b's "Hidden behaviors / open questions" when the L3 work covers them.
- Out of scope (defer to Phase S-5 finalization): L3
### VAR:entries for newly-listed variables. Local-state Sections analogous to per-function locals for large closures.
Scope-corrections from class-method-nested defs
When a class method contains nested defs, the AST scope tag is
cls:Class (in <method>) (Section 5.2). If the AST is older and shows just cls:Class,
update both L2a and L2b rows during the cluster's work — this is part of L2b extension.
Section 12 — Verification rules cadence
The skill recommends a cadence split between pre-edit and post-edit checks. Specific rule contents are project-defined via the config.
Pre-edit: per individual edit
verification.pre_edit_rules is a list of project-defined checks the agent runs before
each edit decision. Examples:
- Confirm line numbers (grep for the exact function name in current source).
- Trace call chain (find all upstream callers).
- Interface check (signature compatibility with callers).
- Ordering check (post-move dependencies still resolve).
- Path derivation check (sidecar paths consistent with new format).
- Scope check (
globalvsnonlocalcorrectness).
These fire per-edit because they prevent wrong edits before they happen — they cannot be batched.
Post-edit file-wide scans: per cluster
verification.post_edit_commands is a list of shell commands the agent runs once per
cluster, at the cluster seam (not per individual edit). Examples:
python -m py_compile <module>(Python syntax check).- Grep for orphaned method references.
- Callback-definition existence check.
- Project-specific lint or test commands.
Per-cluster cadence: running these after each individual edit in a 5-edit cluster multiplies cost without catching anything per-cluster wouldn't.
Bisect on failure
If post-edit verification fails after a cluster, bisect by reverting fixes in reverse application order. Re-run verification after each revert. The error message usually points at the offending edit, so bisection is typically O(1) — cheaper than per-edit verification across the cluster.
Section 13 — Session report finalization gate
At the end of every session that touched docs or applied edits, a finalization gate runs before the session report is written.
Default behavior
Overwrite <handoff>/session_report.md (path is paths.session_report config key).
Prior session report archived to <archive>/<suffix>_session_report.md first.
Self-check checklist
Agent runs a categorical pass before presenting the report:
- All in-progress L3 entries reached
documentedstatus (no orphans)? - Every approved source edit recorded in
fixes_log.md? - Every newly-created
<name>bug.mdhas a status banner (OPEN / RESOLVED)? - Index cascade complete — L1 / L2a / L2b match current source state?
- If mid-cluster: checkpoint marker written at L2a top with "next: X"?
- Forward-pointer for next session noted?
- Any TODO markers in L2b/L3 resolved this session but still present in text?
Results presented as a structured pass/fail list; failures listed with brief detail.
Single-message gate
Session self-check: [results]
Draft report preview: [content, ~50 lines]
Anything to add, edit, or flag for next session?
Otherwise: archive prior session_report to <archive_path>, overwrite session_report.md.
Human responds with edits or "go." Only if they say "don't overwrite" does the fallback fire. The gate is a single round-trip in the common case.
Fallback options if human declines overwrite
- Concat: append the new report to the existing
session_report.md. Single file grows. - New file with suffix: write to
<handoff>/session_report_<suffix>.mdwhere suffix follows project config (paths.session_report_suffix_format, default<YYYYMMDD>). Existing report untouched.
Archive-before-write
The archive step (move prior session_report.md to dated archive) runs BEFORE the new
write. If the new write fails, the prior report has already been preserved. No risk of
losing both.
Section 14 — Source-internal metadata
Conditional convention for projects that maintain in-source datestamps and version
constants (__version__, __date__, last_update, version, etc.) at the top of
modules.
Bump matrix
| Field type | Bump on edit-enabled doc-pass edits? | Rationale |
|---|---|---|
Date-class (last_update, __date__, last_modified) | Yes — set to today's date in project format | The field's semantics are "when was this file last touched"; not bumping makes it a lie. Cost is one one-line edit. |
Version-class (version, __version__) | No for doc-driven cleanup; Yes for feature releases | Salvage cleanups don't change behavior; reserve version bumps for feature deliveries (matches semver intent). |
L2a header last_updated field | Always, every session that touches the index | Standard wiki-doc convention, in scope for this skill. |
| Filesystem mtime | n/a — auto-managed by OS | Drives session-start staleness checks. |
Project-config keys
metadata.date_field_name(no default — required if any date-bumping desired).metadata.date_format(default%Y%m%difdate_field_nameis set).metadata.version_field_name(no default).metadata.bump_version_on_salvage(defaultfalse).
If metadata.date_field_name is absent or null, no bumping happens — the convention is
opt-in.
Verification
Optional grep at end-of-cluster step 6 for unbumped fields. The agent surfaces:
"Detected last_update = 20260421 in source; current date is 20260501. Bump per
metadata.bump_rules?" Human approves or skips.
Section 15 — Variable line-number refresh
L2b variable rows include a line-number column (Section 5.3). The AST script's --vars
output drives variable line-number refresh in L2b, mirroring the function-row pattern.
Same cadence as function refresh: per-cluster batched, automatic on Reference Refresh
(Section 10), automatic at end-of-cluster step 7.
Section 16 — Active maintenance
For modules with active status — post-salvage edits typically happen outside the
wiki-doc protocol (regular development work, collaborator pull requests, etc.). The
skill cannot enforce edit-time discipline outside its protocol. This section defines
the realistic posture.
Skill posture
- Within wiki-doc protocol (edit-enabled doc pass during salvage or maintenance): cascade applies, Section 8 protocol fires, all rules above hold.
- Outside protocol (regular dev edits): unavoidable drift accumulates between L1/L2/L3 and source. The skill's catch-up mechanism is Reference Refresh (Section 10).
Drift detection at session start
Recommended: agent compares file mtime to L2a last_updated at every session start. If
file is newer, alert and offer R-1. Already implemented as a session-start check in
mature projects.
Optional CI / git hook
For projects with active concurrent development, an optional git pre-commit hook or CI
job can run ast_index.py --diff against a stored snapshot, alerting when source
changes affect functions documented in L2a. The skill describes the pattern; project
implements (it's environment-specific).
Sample pre-commit hook outline:
# .git/hooks/pre-commit (project-supplied)
python tools/ast_index.py <module>.py --diff .wiki-doc/<module>.snapshot.tsv \
| grep -q DRIFT \
&& echo "WARN: wiki-doc drift detected; run R-1 after commit." || true
Section 17 — Version control integration
Optional. Activates only when vcs.enabled: true in the project config.
(vcs = version control system.) When disabled, the skill makes no commits,
no branches, no worktrees — it operates as if VCS does not exist.
Useful for projects where VCS is managed through a separate workflow (e.g.,
external sync to a Git host from a different machine, or a workspace that is itself a
non-canonical working copy).
17.1 Commit granularity
Commits fire at the cluster seam — once per cluster, after post-edit verification passes. NOT per individual fix. Reasons:
- The cluster seam is the natural verified-work unit. Pre-seam state is mid-protocol and not necessarily consistent.
- Per-fix commits create noise: 5 fixes in a cluster → 5 commits, none of which individually carry verification.
- Per-cluster commits align with the rollback model (Section 8 step 9): if verification
fails, the cluster is reverted in a single
git resetrather than five individual reverts.
The cluster seam in the protocol's order:
Cluster of fixes applied (Section 8 steps 1–5)
→ Post-edit verification (Section 12 + Section 8 step 6)
→ Index cascade (Section 8 step 7)
→ Append fixes log (Section 8 step 8)
→ [VCS commit happens here, if enabled]
→ Session report finalization gate (Section 13)
The commit lands AFTER the index cascade and fixes-log append, so the commit captures both source changes AND documentation updates in one atomic commit.
17.2 Commit message format
Configurable via vcs.commit_message_template. Default template:
{module}: {summary}
{fix_list}
- Net source delta: {delta} lines
Verification: {verification}
Cluster: {cluster_id}
Substitution variables:
{module}— affected module's bare name{summary}— one-line cluster summary, supplied by the agent{fix_list}— bullet list of fixes with line ranges{delta}— net source-line delta with sign{verification}— verification commands and outcome{cluster_id}— cluster identifier or descriptive name
Example commit (filled-in default):
mspfileloaderv14: open_ml_params_window cluster cleanup
- Outer _get_ml_context deleted (lines 6776-6797)
- Inner _read_ml_from_json deleted (lines 6764-6772)
- _on_key dead binding deleted (lines 6890-6905)
- Net source delta: -38 lines
Verification: py_compile OK, self._ audit OK, callback grep OK
Cluster: S7-cluster-1
17.3 Branch strategy
Project-config'd via vcs.branch_strategy:
current(default) — agent commits to whatever branch is currently checked out.cluster_branch— agent creates a new branch per cluster (<module>-<cluster_id>), commits there, leaves it for human review and merge.worktree— agent uses git worktrees (Section 17.4) for parallel cluster experimentation.
For most projects, current is correct: clusters are small enough that branch overhead
isn't justified. cluster_branch is useful when multiple agents or contributors need
parallel cluster work without stepping on each other.
17.4 Worktree pattern (documented, opt-in)
For projects that want to isolate cluster experimentation, the worktree pattern provides a parallel working directory without affecting the main checkout. Useful when a cluster's bisect-rollback (Section 8 step 9) might be invoked multiple times or when experimental refactors need to stay isolated until verified.
Project-config'd via:
vcs:
worktree_create_command: "git worktree add ../{module}-{cluster_id}-experiment HEAD"
worktree_remove_command: "git worktree remove ../{module}-{cluster_id}-experiment"
Substitution variables: {module}, {cluster_id}. Both commands are adjustable —
the values shown are the recommended defaults.
Workflow when vcs.branch_strategy: worktree:
- Cluster begins → agent runs
worktree_create_command. - Agent applies fixes in the worktree directory.
- Verification runs in the worktree.
- On success: merge worktree branch back to the main branch via
git merge, then runworktree_remove_command. - On failure (verification fails): run
worktree_remove_command(no merge); fixes are discarded along with the worktree.
The worktree pattern is documented but not recommended by default. For most
clusters the in-place current strategy is simpler and faster. Adopt worktree only
when parallel experimentation or risky refactors justify the overhead.
17.5 Pre-approved fix categories (opt-in)
For fixes that match pre-defined safe criteria, the agent may apply without per-fix human approval. Still logged (Section 8 step 8); still surfaced in the cluster summary at the seam, where the human reviews all pre-approved fixes en masse before approving the commit.
Opt-in only — no skill default. Projects that want this list categories explicitly in config:
edit_protocol:
pre_approved_categories:
- zero_caller_dead_code # Section 8 in-scope item: zero callers, scope clear
- rotted_comment_cleanup # Stale comments referencing removed code
# Additional project-defined categories
When the agent identifies a fix candidate, it checks the list:
- Match found: apply without per-fix approval. Log normally. Include in cluster
summary marked
[pre-approved]. - No match: standard Section 8 protocol — per-fix human approval required.
Cluster seam still gates the commit. Human reviews all pre-approved fixes alongside
manually-approved fixes at the seam, before the commit lands. Revert is one
git reset HEAD~1 if anything is wrong.
Risk management:
- Pre-approved categories are project-explicit — the skill ships with no defaults to prevent accidental enablement.
- Cluster summary includes a
[pre-approved]tag on each pre-approved fix, so the human can spot them at a glance. - Same Section 8 verification rules apply — pre-approval doesn't skip pre-edit checks.
- Same cluster-seam post-edit verification — failure triggers bisect-rollback as normal.
17.6 Project-config keys
Summary of vcs.* keys (full template in wiki-doc.config.template.yaml):
| Key | Default | Purpose |
|---|---|---|
vcs.enabled | false | Master toggle. Skill makes no VCS calls when false. |
vcs.commit_message_template | (built-in default, Section 17.2) | Commit message format string |
vcs.branch_strategy | current | One of current / cluster_branch / worktree |
vcs.worktree_create_command | git worktree add ../{module}-{cluster_id}-experiment HEAD | Used when branch_strategy is worktree |
vcs.worktree_remove_command | git worktree remove ../{module}-{cluster_id}-experiment | Cleanup after worktree merge or revert |
edit_protocol.pre_approved_categories | [] | Opt-in list of safe-to-auto-apply fix categories |
When vcs.enabled: false, all other vcs.* keys are ignored.
Section 18 — Sub-agent pattern
Read-only contract
Sub-agents are read-only by skill contract. They perform search, cross-reference, trace, discovery, and computation. They do NOT update documentation. They do NOT perform edits. They do NOT execute project commands that mutate state.
This contract is non-negotiable in the current version of the skill. If a future project demands sub-agent dispatch for narrow post-approval write tasks (e.g., line-number-only L2a/L2b updates after R-1 approval), that is a deliberate skill amendment requiring its own design pass.
Tasks suitable for sub-agents
- Searching L3 by heading and reading the matched entry.
- Tracing call chains across L2a (multi-module).
- Cross-referencing L2a entries against current source.
- Running
ast_index.pyand reporting results (R-1 discovery phase, Section 10). - Audit phase output review (Section 7, Phase S-3 candidate review).
- Hidden-behavior sweep within a single module (Phase S-5 step 4).
Tasks NOT suitable for sub-agents
- Writing or modifying any documentation file.
- Editing source code.
- Running test suites or anything that mutates project state.
- Approving fixes on behalf of the human.
Dispatch pattern
Main agent passes the sub-agent: function name(s), file paths, the specific question to answer, and a short context briefing. Sub-agent searches, reads, computes, returns findings. Main agent integrates, surfaces to human, performs writes if any.
Section 19 — Deferring protocol expansions
When a protocol gap is identified mid-pass but cannot be addressed in the current pass, file the deferral as a single-line breadcrumb in the most discoverable L3 entry plus an entry in the project's gap log. Do NOT commit to a resolution; the breadcrumb just makes the deferral discoverable.
Breadcrumb format
In the most discoverable L3 entry (e.g., the closure-root entry for a closure-local
state issue, or the class __init__ for a class-state issue), add a single Dev-notes
row:
**Dev notes:**
- *(deferred protocol gap)* Closure-local state for this mega-closure is not formally
mapped in L2b. Tracked in `<handoff>/<project>_skill_gaps.md` Gap N.
Brief, pointer-only. The detailed write-up lives in the gap log, not in the L3 entry.
Gap log entry format
In <handoff>/<project>_skill_gaps.md:
## YYYY-MM-DD — <module> <cluster>
### Gap N — <one-line summary>
**What's missing in the skill**
[1-3 paragraphs]
**Where this matters**
[1-2 paragraphs with concrete example from this project]
**Working agreement adopted for now**
[1-3 paragraphs describing the project's current handling]
**To investigate later**
[bullets — what the skill should consider when this gap is addressed]
This pattern emerged from real GlycoMSP usage and is the source of the v1 protocol's 8-gap evolution. It works because deferrals stay discoverable without committing the project (or skill) to a particular resolution.
When deferrals accumulate
Periodic gap-log review (project-driven cadence) consolidates deferrals: some get resolved by the project, some get upstreamed to a skill amendment, some stay as documented working agreements indefinitely. The breadcrumbs in L3 entries are updated when the gap is resolved.
Upstreaming a gap to the skill
If a deferred gap might be valuable beyond your project — i.e., the working agreement
could be a useful default for other wiki-doc users — consider upstreaming it. See
CONTRIBUTING.md for the proposal format and review process. Working agreements that
have been stable across multiple sessions or projects are the strongest candidates.
Section 20 — Completion validation (final gate)
Before flipping a module from in-progress to active in L1:
- AST completeness: Run AST script, diff against L2a. Every
defmust appear. Missing functions get stub entries. - L3 coverage: Every
documentedfunction in L2a has an L3 entry.stub/pendingare acceptable but noted. - Variable map: L2b exists and is human-reviewed. Cross-check: shared-state arguments in L3 entries appear in L2b.
- Cross-references: All upstream/downstream references in L3 entries resolve to real functions. All L2b reader/writer entries exist in L2a.
- Line number spot-check: Compare 3-5 functions between L2a and source. Re-run AST if mismatch.
- Pre-S-3 audit findings resolved or deferred. Each duplicate-pair from S-3 either resolved (one copy deleted) or explicitly deferred via Section 19.
- Bug files have status banners. Every
<name>bug.mdfiled during salvage has a current**Status:**banner (OPEN with rationale or RESOLVED with date). - Fixes log reconciled.
fixes_log.mdhas entries for every approved source edit during this salvage. Line-delta artifact (<module>_line_deltas.md) sums match. - Calibration spot-check. Sample 3 L3 entries (one trivial, one mid-complexity, one high-density). Verify each follows Section 6 rules: source-anchored claims, minimum-fields template, eligible dev notes, no forward-looking speculation in dev notes.
If all pass: update L1 status to active, update date, note coverage percentage.
Section 21 — AST script reference
The bundled script scripts/ast_index.py is the single tool that powers Sections 7
(salvage), 9 (cascade), 10 (Reference Refresh), and 15 (var refresh).
Function index (default mode)
python ast_index.py <source.py>
Output: DEF\t<name>\t<line>\t<scope> rows, sorted by line number.
Auto-detected scope (NEW in v1):
top— module-level def.cls:ClassName— class method (direct member).cls:ClassName (in <method>)— nested def inside a class method.cl:<closure_name>— closure-local def (named-function closure).cl:<outer> (in <inner>)— sub-closure-local def.
This eliminates the manual scope-correction work that was required in v0.2.
Variable index (--vars)
python ast_index.py <source.py> --vars
Output: adds VAR\t<name>\t<line>\t<scope> rows. Same scope auto-detection as
functions.
All (--all)
python ast_index.py <source.py> --all
Output: adds CLASS\t<name>\t<line>\t<scope> rows for class definitions.
Pre-S-3 audit mode (--audit, NEW)
python ast_index.py <source.py> --audit
Output: structured report with three sections:
- Duplicate-name candidates: same
defname in multiple scopes. Each pair listed with both line numbers. - Zero-caller candidates: defs with no observed call sites within the file (intra-file only).
- Shape anomalies: defs nested inside string literals, defs inside
if False:branches, etc. (heuristic).
Powers Phase S-3 (Section 7).
Diff mode (--diff <snapshot>, NEW)
python ast_index.py <source.py> --diff <previous_snapshot.tsv>
Output: drift report comparing current AST against a saved snapshot. Lists shifted, added, deleted, and renamed defs/vars. Powers Reference Refresh (Section 10).
To produce a snapshot for later diff:
python ast_index.py <source.py> --vars > <snapshot>.tsv
Output format
Tab-separated values, one entry per line:
KIND<TAB>NAME<TAB>LINE<TAB>SCOPE
Sortable by cut -f3 | sort -n if needed.
Python-specific note
The shipped script is Python-specific (uses Python's ast module). Projects in other
languages need to author their own AST tool conforming to the documented output format.
The structure generalizes — any AST library can produce equivalent output — but the
shipped tool covers Python only.
For other languages, suggested approaches:
- JavaScript/TypeScript:
@babel/parserortypescriptcompiler API. - Go:
go/aststandard library. - Rust:
syncrate. - C/C++: Clang's libclang.
The output format must match (KIND\tNAME\tLINE\tSCOPE). All other tooling in this
skill consumes that format and is language-agnostic.
Section 22 — Glossary
- L1, L2a, L2b, L3 — Levels of the documentation hierarchy. See Section 2.
- S-1 through S-5 — Salvage protocol phases. See Section 7.
- R-1 — Reference Refresh. See Section 10.
- Cluster — A thematically-related batch of work performed in a single sub-session, bounded above by context budget or human-defined cadence and below by a single function or fix. Clusters are the unit at which post-edit verification, index cascade, and fix-log entries fire ("the cluster seam"). A typical L3-drafting cluster covers 5–15 related functions; a typical fix cluster covers 1–5 related edits. Clusters can be thematic (a class's methods together) or structural (a closure's helpers together) — the human picks the boundary, the protocol enforces what fires at the seam.
- Cascade — The cascading update of L1/L2a/L2b/L3 line numbers and metadata after one or more source edits. See Section 9.
- Cluster seam — The point between clusters where post-edit verification, index cascade, fixes-log append, and rollback-on-failure all run.
- Frozen anchor — An anchor in the docs whose line number is preserved as a historical snapshot rather than auto-shifted. See Section 9.
- Doc-only pass — A wiki-doc session in which source files are not modified. The default mode.
- Edit-enabled pass — A wiki-doc session in which the human has explicitly enabled source edits per Section 8.
- Audit mode —
ast_index.py --audit. Surfaces duplicates, zero-callers, shape anomalies before S-4 begins. - Diff mode —
ast_index.py --diff <snapshot>. Powers Reference Refresh.
Quick rule reference
- Read L1 first every session. Spot-check version/date for relevant modules.
- L2a is the working layer. Most tasks resolve here.
- L2b is human-triggered. Variable map on explicit request.
- Line numbers are auto-generated via AST. Only L2a/L2b store them.
- L3 is accessed by name. Sub-agents grep
### nameheadings. - Updates propagate bottom-up. Source → L3 → L2a/L2b → L1.
- Sub-agents are read-only. No exceptions in v1.
- Doc-only is default. Edit-enabled requires explicit opt-in.
- Edit-enabled requires Section 8 protocol. Suggest → approve → apply → verify → log.
- Verification cadence: pre-edit per-edit, post-edit per-cluster.
- Cascade is per-cluster. AST refresh, index update, log append at the cluster seam.
- Frozen Last-edit by default. Project may opt into auto-shift.
- Calibrated entries. Source-anchor claims; eligible dev notes only; speculation goes to Future Considerations.
- Defer cleanly. Breadcrumb in the most discoverable L3 entry; full deferral in the gap log.
- Completion gate before active. Section 20's nine checks before flipping L1 status.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 468k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 468k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 468k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |