/arrow-maintenance

name: arrow-maintenance
description: Navigation and audit overlay for linked-intent development. Use when working with docs/arrows/ — orienting via index.yaml, auditing spec-to-code coherence, detecting reverse orphans and drift, splitting/merging/renaming/re-parenting segments. Dual-mode: ambient guidance when the overlay is present (catch-and-recommend), or explicit /arrow-maintenance command for a directed audit-and-update pass.

Arrow Maintenance

The arrow-maintenance overlay scales linked-intent-dev for projects too large to hold in one context window. It provides a navigation index, systematic audit, and brownfield bootstrap.

This skill operates in **two modes**. Detect which mode applies before acting.

Two modes

**Ambient mode.** Auto-triggered on arrow-adjacent prompts when `docs/arrows/` exists. Posture is *catch and recommend* — notice relevant work, surface findings, edit only as the surrounding conversation authorizes. File writes happen opportunistically (e.g., updating an arrow doc's coverage table alongside a linked-intent-dev edit on the same segment). Record arrow lifecycle events (split, merge, rename, re-parent, status transitions) rather than erasing them. Do not initiate a systematic audit-and-update pass in ambient mode.

**Command mode.** Invoked explicitly as `/arrow-maintenance`. Posture is *directed action* — the user has asked for the pass. Run an audit-and-update pass, apply unambiguous fixes in place, and surface the rest for user decision. Does not pause at synthetic phase boundaries — it is a single directed pass.

When `/arrow-maintenance` is invoked

Inspect the project and dispatch on state:

• **Overlay present (`docs/arrows/` exists)** → run the audit-and-update pass (below).
• **LID docs present (HLD + at least one LLD) but no `docs/arrows/`** → generate the overlay from existing LID docs: populate `index.yaml` with one `arrows:` entry per design-tree node — one leaf entry per leaf LLD (the EARS-owning nodes) and one grouping entry per sub-HLD node — recording the tree's nesting via `parent`/`children` links, status `MAPPED`, `sampled: {today}`, `audited_sha: null`; create one per-segment arrow doc per leaf LLD at its tree-mirrored path (`docs/arrows/<path>/<leaf>.md`), referencing the existing LLD and any known tests/code. Sub-HLD nodes are directories, not arrow docs — their `index.yaml` entry sets `detail` to the sub-HLD's design doc (`../intent/<path>.md`) instead. Do not generate new HLD, LLD, or EARS skeletons (those exist).
• **Neither LID docs nor overlay** → the user typed `/arrow-maintenance` on a project that isn't ready for it. Don't just print a redirect — describe what you found and offer to dispatch: "I see no LID installation here. You probably want `/linked-intent-dev` if this is a greenfield project (give it a description of what you want to build; it bootstraps LID as part of Phase 1), or `/map-codebase` if you're bringing LID to an existing codebase. Shall I run one of those instead, or did you mean something else?" Then proceed based on the user's answer.

Audit-and-update pass (command mode)

Every `/arrow-maintenance` run, in order:

1. **Repair broken overlay state.** Malformed `index.yaml`, missing per-segment docs referenced by the index, stale schema versions — these are this skill's domain, so fix them first.

2. **Run the five audit checks** (see `references/audit-checklist.md`):

• **Reference coherence**: do arrow-doc pointers resolve? Are cited EARS specs present? Are LLD section headings as referenced?
• **Coverage**: does every behavioral spec have at least one eval assertion citing it?
• **Staleness**: compare `audited` and `audited_sha` against current state to find segments whose files changed since last audit.
• **Drift signals**: modified code since `audited_sha`, specs changed without test updates, tests passing but missing `@spec` annotations, `@spec` annotations pointing to missing spec IDs (*reverse orphans*).
• **Orphan artifacts**: LLDs, specs, or code files not listed in any arrow doc's References section.

Exclude the reserved `docs/arrows/_experiments/` subtree from all five checks — it is owned by `lid-experimental`, not this skill, and is never audited, cleaned up, or regenerated here (see `docs/intent/arrow-maintenance/arrow-maintenance-design.md`).

When a project-local coherence script is declared under `## LID Tooling` in `CLAUDE.md` (as `Coherence check: {path}`), invoke that script and treat its output as authoritative for the deterministic checks it performs. Languages and paths vary by project — trust the declaration. If the declaration is missing or the declared path does not exist, perform the checks in-prompt. A reference Node implementation is bundled at `references/coherence-check.mjs` that users may copy to their project and declare in CLAUDE.md.

3. **Apply unambiguous fixes in place:**

• Regenerate `## Spec Coverage` tables in affected arrow docs from source scans.
• Regenerate `## References` sections from source scans (grep for `@spec`, check file paths exist).
• Update `status` / `next` / `drift` fields in `index.yaml` where the new state is clear.
• Clean up `unmapped.docs`: assign entries to segments where the assignment is unambiguous; flag the rest for user assignment.
• Refresh `audited: {today}` and `audited_sha: {current git HEAD}` on each audited segment.

4. **Surface everything else for user decision:**

• Reverse orphans — ask whether to create the missing spec, delete the annotation, or treat as an alias of an existing spec. Do not auto-resolve.
• Ambiguous segment assignments for `unmapped.docs` entries.
• Candidate lifecycle events (splits, merges) detected from drift signals.
• Any finding where the right fix depends on intent.

5. **Produce a structured report** at the end: list findings, distinguishing those that were automatically resolved from those requiring user decision. Include location (segme