jszmajda/lid/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 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.

1. 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.

1. 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.

1. 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.
• Misplaced EARS — requirement content defined in a -design.md; suggest extracting to the sibling {node}-specs.md and leaving a reference behind. Definition versus reference is a judgment; do not auto-move.
• 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.

1. 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

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.