Documentation

Guide

Maintain knowledge

Durable knowledge drifts as code changes. This guide keeps it accurate in three loops: spec content, spec-to-code references, and summaries.

1. Grow and reshape specs

In sdlc-light and sdlc-full, the cumaru-specs skill has three recipes. Each asks you to confirm every new area or split.

  • Bootstrap: create a skeleton area for behavior that exists.
  • Deepen: fill an area with requirements grounded in the code.
  • Consolidate: rewrite a body that reads like a changelog into current state.
Deepen the auth spec from the current code.

Other domains keep durable knowledge elsewhere, for example topology/ or coverage/, with their own skills. See the domain profiles.

2. Close coverage gaps

Find source files that no spec references:

cumaru coverage --gaps

Then ask your agent to use cumaru-refs. It decides which spec owns each file and writes rows into that spec's reference tag with cumaru tag set. Each row must point at a source file relative to the project root.

Run cumaru-refs and close the coverage gaps in src/auth.

Use cumaru coverage --strict in CI to fail on uncovered, stale, or invalid rows.

3. Repair summaries

cumaru doctor and cumaru tree --deep report missing or invalid summary: fields. A valid summary has 32 to 512 characters. Ask for cumaru-summarize by name; it only maintains .cumaru summary frontmatter and does not summarize other text.

Repair missing summary frontmatter in .cumaru.

Check the result

cumaru doctor

Sources: cumaru-specs, cumaru-refs, cumaru-summarize, coverage. Prompts are illustrations from this site.