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 (segment, file, line) for each.

## Incremental audit

When `audited_sha` is populated and git history is available, run the audit in incremental mode — inspect only segments whose files changed since `audited_sha`. This is a large performance win on big projects. When `audited_sha` is null (never audited) or git history is unavailable, audit every segment.

## Ambient mode behavior

When the skill is consulted ambiently (not via `/arrow-maintenance`), bias the agent's work on arrow-adjacent tasks:

- **Start from `index.yaml`.** Load it first, before any per-segment doc. Query for unblocked segments (where `blockedBy` is empty and `status` is not `OK` or `OBSOLETE`).
- **Load detail on demand.** Only load the per-segment arrow doc once a specific segment is implied. Follow its `## References` into LLDs, spec files, tests, or code as needed.
- **Surface drift rather than silently repair.** When you notice a reference mismatch, reverse orphan, or stale segment during other work, mention it. Let the user or `linked-intent-dev` drive the fix.
- **Participate in writes the conversation is already doing.** When `linked-intent-dev` is editing a segment, update that segment's arrow doc and `index.yaml` entry in the same cascade — this is opportunistic, not initiated by you.

## Authoritative sources

When information appears in multiple places, this is the authority rule:

- **Segment state fields** (`status`, `sampled`, `audited`, `audited_sha`, `next`, `drift`, `blocks`, `blockedBy`, `merged_into`) live authoritatively in `index.yaml`.
- **Per-segment arrow doc's References and Spec Coverage** are *derived views* — regenerated from source scans during audit. Do not hand-edit them to contradict source.
- **`index.yaml` schema** is defined authoritatively in `docs/intent/arrow-maintenance/arrow-maintenance-design.md` (the sub-HLD that owns the shared overlay); `references/index-schema.md` is the working copy. Cross-plugin schema changes defer to the sub-HLD.
- **Spec-file header format** (the LID-on-LID inversion) is defined in `docs/intent/linked-intent-dev/linked-intent-dev-design.md` — this skill reads from that schema.
- **`@spec` placement rule** (entry point of behavior's implementation graph) is defined in the `linked-intent-dev` skill.

## Arrow doc format

An arrow segment is the territory owned by one **leaf** LLD — the node that owns EARS specs — and its boundary is that leaf's prefix in the path-concatenated EARS IDs (e.g., `grep SCALE-MAINT` gathers the segment). Each leaf segment has one markdown file under `docs/arrows/` at the path mirroring its design doc under `docs/intent/` (e.g., `docs/arrows/arrow-maintenance/maintenance.md` mirrors `docs/intent/arrow-maintenance/maintenance/maintenance-design.md`); at depth-2 this is a flat set of `{segment-name}.md` files. Sub-HLD (grouping) nodes own no EARS and no segment — they are directories, not arrow docs. See `references/arrow-doc-template.md` for the template. The arrow doc is an *orientation page*, not a design doc — pointers + coverage table, no duplicated design content.

## Status enum

| Status | Meaning |
|---|---|
| UNMAPPED | Not yet explored |
| MAPPED | Structure known, specs not verified against code |
| AUDITED | Specs verified — implementation status understood |
| OK | Fully coherent — all specs implemented |
| PARTIAL | Some specs missing or partial |
| BROKEN | Code and docs have diverged significantly |
| STALE | Docs exist but outdated |
| OBSOLETE | Superseded, kept for historical reference |
| MERGED | Combined into another arrow (use `merged_into` field) |

Normal progression: `UNMAPPED → MAPPED → AUDITED → OK`.

## Lifecycle events

Segments evolve. Five first-class events. This skill is the owner that executes them on an existing overlay; `linked-intent-dev` recognizes one mid-change and hands off here. The mechanics and atomicity guarantees are specified authoritatively in `docs/intent/arrow-maintenance/arrow-maintenance-design.md § Lifecycle Events`.

- **Split**: one segment → two. Create the new segment's arrow doc, move relevant references, update both docs to reference each other, record in `index.yaml`. If detected mid-change, ask whether to split now or defer — deferring is preferred. Split at clean breaks, not mid-edit.
- **Merge**: two segments → one. Pick primary, move references, mark secondary as `MERGED` with `merged_into: {primary-name}`. Tombstone or delete the secondary's arrow doc.
- **Rename**: a leaf segment's name changes (e.g., `auth` → `identity`). Because that name is the leaf prefix of the segment's path-concatenated EARS IDs, the rename rewrites every spec ID under it (`AUTH-UI-001` → `IDENTITY-UI-001`) across the spec files **and** every `@spec` annotation in code and tests that cites those IDs. In the same pass, walk *all* other cross-references: the arrow-doc filename, the `index.yaml` entry key, `parent`/`children` links, `blocks`, `blockedBy`, `merged_into`, `taxonomy` membership, and every other arrow doc's References section. Rename is not rename-and-hope — spec files, docs, `index.yaml`, and code annotations land together or not at all.
- **Re-parent**: a subtree moves to a new parent in the design tree (e.g., the `runner` leaf moves from under `prompt-eval` to under `orchestration`). Because an EARS ID *is* the root-to-leaf path, re-parenting rewrites the path-concatenated IDs of every spec in the moved subtree (`PEVAL-RUN-014` → `ORCH-RUN-014`) and every `@spec` annotation citing them across code, tests, and docs, plus the `parent`/`children` links in `index.yaml` for the moved node and both the old and new parents. Like rename, this happens atomically in one session.
- **Status transition**: `UNMAPPED → MAPPED → AUDITED → OK` with detours as needed. Timestamps (`sampled`, `audited`, `audited_sha`) record when each transition happened.

Rename and re-parent are the **tooled, atomic restructuring operation** this plugin owns: path-concatenated EARS IDs are stable under ordinary growth and change *only* under a deliberate rename or re-parent. A partial application — IDs rewritten in the spec file but not in code — is exactly the cross-reference rot the atomicity requirement exists to prevent.

## Coordination with linked-intent-dev

| Concern | Owner |
|---|---|
| Per-change HLD/LLD/EARS/test/code work | linked-intent-dev |
| Cascade at change time | linked-intent-dev |
| Arrow doc + `index.yaml` updates *during* a change | linked-intent-dev (has segment in context) |
| `unmapped.docs` cleanup | arrow-maintenance during audit; linked-intent-dev when it notices an unmapped doc it can assign in passing |
| Systematic audit across segments | arrow-maintenance |
| Drift detection between sessions | arrow-maintenance |
| Brownfield mapping | arrow-maintenance (`/map-codebase`) |
| Overlay bootstrap on existing LID projects | arrow-maintenance (`/arrow-maintenance` command mode) |
| Lifecycle events (split, merge, rename, re-parent, status) | Either skill; arrow-maintenance has richer guidance for multi-segment events and owns the atomic rename/re-parent operation that rewrites path-concatenated EARS IDs and their `@spec` annotations across docs and code |

## No prescribed audit cadence

The skill does not prescribe "run audit every N commits" or "run weekly." Surface staleness signals when consulted; let the user choose the rhythm.

## Reference files

- `references/index-schema.md` — full `index.yaml` schema.
- `references/arrow-doc-template.md` — per-segment arrow doc template.
- `references/audit-checklist.md` — the five audit checks in actionable form.
- `references/coherence-check.mjs` — reference Node implementation of deterministic checks. Optional; any equivalent in any language works.
- `references/README-template.md` — template for the `docs/arrows/README.md` that projects install alongside their overlay.