Skip to content

henry4204aaa/wiki-doc-skill

wiki-doc

Verified

3-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".

FileKindSize
SKILL.mdskill md61.8 KB
examples/README.mdmarkdown3.2 KB
examples/glycomsp_companion.mdmarkdown11.5 KB
scripts/ast_index.pyscript17.5 KB

examples/glycomsp_companion.md

View on GitHub
# GlycoMSP Project Companion to wiki-doc Skill

This document is the project-side companion that layers GlycoMSP-specific concrete
content on top of the generalized wiki-doc skill (SKILL.md). It serves as both:

1. The reference for GlycoMSP's wiki-doc configuration and conventions.
2. An example for other projects authoring their own companion files.

The generalized skill is project-agnostic; this companion encodes the decisions
GlycoMSP has made for paths, naming, verification rules, and terminology mappings.

---

## Phase numbering migration (v0.2 → v1)

The v1 skill inserts **S-3 (Pre-documentation audit)** as a new phase. The prior
phases shift accordingly:

| v0.2 | v1 | Purpose |
|------|----|---------|
| S-1 | S-1 | Harvest review knowledge |
| S-2 | S-2 | Scaffold structure (AST + L2a) |
| — | **S-3** | **Pre-documentation audit (NEW)** |
| S-3 | S-4 | Systematic documentation (L3 drafting) |
| S-4 | S-5 | Variable mapping (L2b finalization) |

Earlier GlycoMSP session reports, fixes_log entries, and bug files use the v0.2
numbering — read them as such. Active L1 / L2a / L2b docs are updated to v1 numbering
opportunistically as they're next touched (no bulk rewrite of historical documents).

`handoff/wiki_protocol.md` and `handoff/wikidoc_skill_gaps.md` retain v0.2 numbering;
both have a v0.2-numbering note at the top of file.

---

## Pass-type mapping (Mode A / Mode B → doc-only / edit-enabled)

GlycoMSP's `CLAUDE.md` defines **Mode A** (offline, source not edited; Henry edits
on Drive) and **Mode B** (online synced; Claude Code and Henry edit the same file).

These map to the skill's pass types as follows:

| GlycoMSP CLAUDE.md term | wiki-doc skill term | Behavior |
|-------------------------|---------------------|----------|
| Mode A | doc-only pass | Agent drafts L3, suggests fixes as patches in `handoff/`, never edits source |
| Mode B | edit-enabled pass | Agent applies fixes per Section 8 protocol after human approval |

When CLAUDE.md says "Mode B is active for this session," the wiki-doc skill operates
in edit-enabled mode. When CLAUDE.md says "Mode A," the skill operates in doc-only
mode regardless of any wiki-doc-specific override.

The skill's edit-enabled protocol (Section 8) is fully compatible with CLAUDE.md's
"Post-Edit Verification Rules" — the seven rules in CLAUDE.md feed the skill's
`verification.pre_edit_rules` config key (see config below).

---

## Project config (`.claude/wiki-doc.config.yaml`)

Concrete values for GlycoMSP:

```yaml
paths:
  handoff_dir: "handoff"
  indexes_dir: "handoff/indexes"
  docs_dir: "docs"
  tools_dir: "tools"
  archive_dir: "../Claude-Workspace/glycomspdevlogs"
  level1_index: "handoff/GlycoMSP_index.md"
  fixes_log_path: "handoff/fixes_log.md"
  session_report: "handoff/session_report.md"
  skill_gaps_log: "handoff/wikidoc_skill_gaps.md"

naming:
  deadcode_filename: "{module}_deadcode.md"
  line_deltas_filename: "{module}_line_deltas.md"
  bug_filename: "{name}bug.md"
  session_report_suffix_format: "%Y-%m-%d"  # GlycoMSP uses dashed dates in archive

verification:
  # Seven rules from CLAUDE.md "Post-Edit Verification Rules" — pre-edit cadence
  pre_edit_rules:
    - line_number_grep         # Rule 1
    - call_chain_trace          # Rule 2
    - interface_check           # Rule 3
    - ordering_check            # Rule 4
    - path_derivation           # Rule 5
    - scope_check               # Rule 6
    # Rule 7 (syntax/symbol check) is post-edit — see below

  # Rule 7 from CLAUDE.md — post-edit cadence
  post_edit_commands:
    - "python -m py_compile {file}"
    - "grep -E 'self\\._[a-zA-Z_]+' {file} | sort -u"     # self._ reference audit
    - "grep -E '(command=|\\.bind\\(|\\.after\\(|trace_add)' {file}"  # callback wiring

cascade_policy:
  last_edit_range: "frozen"     # GlycoMSP convention; archaeology-friendly
  frozen_anchor_prefix: null    # GlycoMSP doesn't use prefix-tagged anchors
  l3_line_cite_handling: "status_quo"

metadata:
  date_field_name: "last_update"
  date_format: "%Y%m%d"          # GlycoMSP convention: 20260501
  version_field_name: "version"
  bump_version_on_salvage: false

audit:
  run_after_s2: false            # GlycoMSP runs audit on explicit request
  report_path: "handoff/{module}_audit_{date}.md"

style:
  appendix_threshold_lines: 100
  l3_minimum_floor_lines: 15

labels:
  # GlycoMSP uses English labels
  scope: "Scope"
  arguments: "Arguments"
  returns: "Returns"
  description: "Description"
  example: "Example"
  upstream: "Upstream"
  downstream: "Downstream"
  dev_notes: "Dev notes"
  last_edit: "Last edit"
  type: "Type"
  owner: "Owner"
  readers: "Readers"
  writers: "Writers"
  inter_module_flow: "Inter-module flow"
  notes: "Notes"

subagent:
  refresh_discovery: true
  l3_search: true
  call_chain_trace: true

vcs:
  # GlycoMSP uses a separate Drive-sync workflow: Mac Studio Claude Code workspace is
  # a cached working copy; Git is managed from Henry's Home PC via Drive sync. Enabling
  # commits in the wiki-doc skill on Mac Studio would conflict with that workflow.
  enabled: false

edit_protocol:
  # No pre-approved categories — every fix gets per-fix human approval per Section 8.
  pre_approved_categories: []

session_report:
  self_check:
    - l3_status_complete
    - fixes_log_consistent
    - bug_files_have_status
    - index_cascade_match
    - checkpoint_marker
    - forward_pointer
    - todo_markers_resolved
  default_action: "overwrite"
```

---

## File-naming conventions and worked examples

### Bug filings (`<name>bug.md`)

GlycoMSP files bugs surfaced during doc passes using a short identifier + `bug.md`
suffix. Examples from v14 salvage:

- `excepthookbug.md` — `_excepthook` stream interleaving + `sys.exit(0)` issue
- `kdnbug.md` — KDN token convention inconsistency across closures
- `skopsbug.md` — unused `untrusted` variable in `load_model_any`
- `applytoexpbug.md` — `_apply_to_exp` passes raw string where parsed dict expected
- `labeldropdownbug.md` — RESOLVED 2026-04-28 (Finding 4)
- `mlsummarybug.md` — `_update_ml_summary` reads nonexistent schema key
- `expstatuslabelbug.md` — `.config(text=...)` on tuple in `export_experiment_json`
- `prepare_dataset_window_bugs.md` — multi-issue tracking (issues a-l)

Status banner format at top of each file:

```markdown
**Status:** OPEN
or
**Status:** RESOLVED 2026-04-28 (see fixes_log.md)
```

### Dead-code tracking (`<module>_deadcode.md`)

GlycoMSP's `v14_deadcode.md` organizes findings by cluster, with each cluster
representing a related batch of dead-code candidates discovered together. Cluster
template:

```markdown
## Cluster N — <description> (date)

**Findings:**
- Outer `<name>` at line X: zero callers across all 8 search patterns
- Inner `<name>` at line Y: shadowed by outer (`<name>` at X)

**Verification:** [grep evidence]

**Decision:** Delete inner. Keep outer (cleaner pattern, LEGB resolves).

**Status:** RESOLVED 2026-04-28 (see fixes_log.md)
```

v14 has 9 clusters total, all RESOLVED via Mode B during the salvage pass.

### Line-delta tracking (`<module>_line_deltas.md`)

GlycoMSP's `v14_line_deltas.md` carries the cumulative source-line delta for
mspfileloaderv14.py across all Mode B sessions:

```markdown
| Date | Cluster | Δ lines | Cumulative | Notes |
|------|---------|---------|------------|-------|
| 2026-04-28 | cluster 1 (S7) | -21 | -21 | open_ml_params_window cleanup |
| 2026-04-28 | cluster 3 (S7) | -6 | -27 | inner _short_id duplicates |
| 2026-04-29 | cluster 4 (S4) | -11 | -38 | _update_main_status_for_batch shadow |
| 2026-04-29 | cluster 5 (S4) | -7 | -45 | widget_alive flatten |
| 2026-04-29 | cluster 7 (S4) | -17 | -62 | dead-string in _on_user_close |
| 2026-04-29 | cluster 8 (S3) | -17 | -79 | submit orphan |
| 2026-05-01 | cluster 9 (S6) | +1 | -78 | run_pseudolabeling return outpath |
| 2026-05-01 | Finding 5 (S6) | 0 | -78 | NEG_LABEL lift |
```

---

## Source-internal metadata

GlycoMSP's `mspfileloaderv14.py` carries:

```python
version = "1.09.3"
last_update = 20260501
```

Both at module top. Per the bump matrix:

- `last_update` — bumped on every Mode B salvage cycle (2026-04-28, -29, -29, -29, -01).
- `version` — left at `1.09.3` throughout salvage; reserved for feature deliveries.

The wiki-doc skill's metadata audit (Section 14) flags any unbumped `last_update`
when a Mode B session has applied edits. GlycoMSP's pre-2026-04-29 sessions did NOT
bump (Gap 7 was filed retroactively); 2026-04-29 onward applies the bump per the
working agreement now formalized in v1 of the skill.

---

## Section terminology mapping

GlycoMSP's v14 module is organized into 8 numbered Sections in the L2a index
(Section 1 — Top-level diagnostics, Section 2 — AppLogger, etc.). The wiki-doc
skill uses "section" generically; GlycoMSP's "Section N" refers to a chunk of v14's
structure.

For non-confusion: when GlycoMSP docs reference "Section 6" or "Section 7," they mean
the v14 closure they describe (`open_prepare_dataset_window` mega-closure for Section
6; `open_ml_analysis_window` for Section 7). These are project-internal labels, not
skill protocol references.

---

## Sub-agent usage in GlycoMSP

GlycoMSP dispatches sub-agents for:

- L3 search-by-heading (Section 18 default)
- Cross-module call-chain tracing (Section 18 default)
- Reference Refresh discovery (Section 10 sub-agent dispatch)

Main agent retains:
- All writes to L1 / L2a / L2b / L3
- All Mode B source edits
- Approval gating
- Session report finalization

This matches the skill's Section 18 contract; no GlycoMSP-specific exceptions.

---

## Salvage history reference

GlycoMSP completed S-1/S-2/S-4 (Phase S-3 audit was added retroactively in v1) for
mspfileloaderv14.py over April 25 – May 1, 2026:

| Phase | Sessions | Scope |
|-------|----------|-------|
| S-1 | 2026-04-25 | Salvage from prior code review |
| S-2 | 2026-04-25 | L2a scaffold (244 functions) |
| S-4 | 2026-04-25 → 2026-05-01 | All 8 sections documented (236/244 = ~96.7%) |
| S-5 | Concurrent with S-4 | L2b extended Sections F + G; Section 6 deferred per Gap 8 |

Status as of 2026-05-01: S-3 was not run (audit phase introduced in v1 after this
salvage). The Section 8 cluster-9 fast Mode B (2026-05-01, +1 line for return outpath)
was the final substantive edit before the module is targeted for `active` flip.

Pending finalization items (per memory log):
- Mode B sweeps for ~55-70 line deletions across 20 cleanup issues
- `expstatuslabelbug.md` (medium-severity) resolution
- Cross-section tickets from Sections 3 / 4 / 7

---

## Adapting this companion to other projects

When you author a project companion for wiki-doc, mirror this structure:

1. **Numbering migration note** — only if your project predated the v1 phase numbering.
2. **Pass-type mapping** — if your project's CLAUDE.md (or equivalent) defines its own
   editing modes, map them to the skill's doc-only / edit-enabled pass types.
3. **Project config block** — full YAML with project-specific values.
4. **File-naming conventions and worked examples** — show your bug-file format,
   dead-code organization, line-delta tracking shape.
5. **Source-internal metadata** — what fields you maintain, how they're bumped.
6. **Section terminology mapping** — disambiguate any in-project terms that overlap
   with skill terms.
7. **Sub-agent usage** — note any project-specific dispatch patterns.
8. **Salvage history reference** — the timeline of when each phase was completed for
   your modules. Useful for onboarding and for understanding which docs predate
   which protocol version.

The goal of the companion is to make the project legible to a fresh agent reading the
skill: SKILL.md teaches the protocol, the companion supplies the concrete instances.
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: 471kUpdated Claude CodeCodexVerifiedInstall
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: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall