/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 both routes: "I see no LID installation here. If this is a new project, `/linked-intent-dev` sets LID up as part of its first phase — give me a description of what you want to build and I'll start it now. If you're bringing LID to an existing codebase, run `/map-codebase` yourself: it reads every file in scope and is token-intensive, so it only starts when you invoke it." If the user picks `/linked-intent-dev`, proceed into it on their answer without asking them to re-invoke. Never start `/map-codebase` yourself, by any route — including reading its `SKILL.md` and following it.

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 six 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.
• **Misplaced EARS**: EARS-labeled intent that a `-design.md` *defines* rather than references — requirement lines with status markers (mechanical screen), or marker-less spec-ID-labeled statements introducing normative content in place (judgment pass). Bare spec-ID mentions are navigation; do not flag them.

Exclude the reserved underscore subtrees under `docs/arrows/` from all six checks — `_experiments/` (owned by `lid-experimental`) and `_map-codebase/` (the brownfield bootstrap's transient sweep files). Neither is 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 aud