Arrow Maintenance

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.