Skip to content

Missing "map" skill: verify and setup both refer to it, data/codebase/ has no writer #1

Description

@anton-matosov

Three documents reference a codebase-map skill or its output, but no such skill ships in .claude/skills/. data/codebase/ is consequently the only data/ lane with no skill that writes it.

All references below are pinned to 249943b.

Evidence

1. .claude/skills/verify/SKILL.md#L51-L54 — audit mode names the skill directly as the fix owner:

   - Stale map docs: for each `data/codebase/` doc, commits touching its
     `source` after its `commit`
     (`git log --oneline <commit>..HEAD -- <source>`) — flag for the map
     skill's refresh mode.

This is a dangling reference: verify is forbidden from fixing anything ("Report, never fix — even a one-character hub-section fix is someone else's commit"), so it can only hand off — and the handoff target does not exist.

2. .claude/skills/setup/SKILL.md#L29-L30 — setup defers the work, but to nothing in particular:

     per-module map under `data/codebase/` is out of scope for setup — file it
     as follow-up work rather than attempting it here.)

3. AGENTS.md#L55-L58 — the operating loop assigns the refresh to the bare session:

   - Code structure changed (module added, split, or moved) → re-read the code
     and refresh the touched `data/codebase/` docs, bumping their `commit` and
     `verified`. `git log <commit>..HEAD -- <source>` finds the stale ones.

Shipped skills at that commit: explore, implement, plan, setup, ship, verify, weekly. No map.

Why this lane specifically

data/codebase/ docs carry the heaviest authoring contract in the schema — SCHEMA.md#L144-L166:

## Codebase map — `data/codebase/<canonical-path>.md`

Derived docs, written only by reading the code: one per component (crate,
package, module), plus `flow-<name>` and `api-<name>`. Keys are canonical — a
component's key mirrors its source path with wrapper segments elided
(`crates/liwe/src/graph` → `data/codebase/crates/liwe/graph`).

Required frontmatter is source + commit ("always quoted — an all-digit SHA parses as a number") + verified, plus a suggested stale_after, described at SCHEMA.md#L35-L36 as:

- `resource`, `tags`, `stale_after`, `usage_window` — optional. Set
  `stale_after` on codebase maps, which go stale the moment the code moves.

A canonical-key rule, a ## Contains tree that iwe tree -k data/codebase depends on, and a quoting trap in required frontmatter — reconstructed from SCHEMA.md on every invocation. That is what the other seven skills exist to encode. And per stale_after, this is the one lane designed to rot: verify can detect the rot but is barred from repairing it.

Suggested scope

A map skill with two modes, mirroring how ship carries a release mode:

  • initial — walk the containment tree, one doc per component at its canonical key, wire ## Contains, stamp source/commit/verified, fill the ✏️ placeholder under ## Getting around in data/codebase.md. This is the follow-up setup defers to.
  • refresh — consume the stale list verify produces, re-read changed sources, bump commit and verified.

Both ending in iwe normalize && iwe schema validate, per the convention every other skill follows.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions