/lid-coach

name: lid-coach
description: "Review a project's current linked-intent-development (LID) usage against LID's own principles and produce a prioritized report of recommendations for getting more out of the methodology. Invoke when the user runs /lid-coach, asks for a LID review, asks how they could use LID better, wants feedback on their LID setup, or asks what LID antipatterns might be present in their project. This is a principle-level advisory review, distinct from /update-lid (configuration reconciliation) and /arrow-maintenance (deterministic structural audit)."
disable-model-invocation: true

LID Coach

Reviews a project's current LID usage against LID's own principles and produces a prioritized set of recommendations. The posture is advisory: the project works; this skill tells the user where patterns are drifting from LID's principles or leaving value on the table.

This skill is invoked only by the `/lid-coach` command. It does not auto-trigger — a principle review reads a broad slice of the project and would be wasteful to fire opportunistically.

What this skill is *not*

• **Not a configuration reconciler.** That is `/update-lid`. When a finding implies a configuration change, point the user there.
• **Not a structural auditor.** That is `/arrow-maintenance` (when the overlay is installed). When a finding is structural in nature — orphans, reverse orphans, adjacent-level coherence, `index.yaml` drift — surface the pattern and recommend `/arrow-maintenance` for the precise enumeration. Do not attempt to enumerate structural instances from sampled reads.
• **Not a file editor.** Advisory posture is load-bearing. Produce the report; the user applies.

Dispatch

On invocation, inspect the project and take exactly one of these actions:

| Detected state | Action | |---|---| | No instruction file (the project's `AGENTS.md`, or `CLAUDE.md` under Claude Code) **and** no LID-shaped artifacts anywhere in the project (no HLD, no LLDs, no specs, no arrow overlay) | Inform the user the project is not LID-configured; recommend `/update-lid`. **Do not proceed with coaching.** | | The instruction file absent or missing LID directives **but** the project has LID-shaped artifacts (see threshold below) | **Proceed with a full review** anchored on the existing artifacts (default Full mode). Surface the missing (or precursor-named) instruction-file directives as a high-priority finding recommending `/update-lid` to reconcile. | | LID directives present, but `docs/intent/` or `docs/high-level-design.md` is missing | Proceed with a **reduced review** of what exists. Surface each missing piece as a high-priority finding and recommend `/update-lid` to reconcile. | | Scoped mode with missing or empty `## LID Scope` | Surface the misconfiguration as a high-priority finding. Run a **conservative project-wide review** treating all paths as in-scope. | | `docs/arrows/index.yaml` present but cannot be parsed | Flag corruption to the user before any principle review. Offer either to proceed with a reduced review treating the overlay as absent, or to pause for the user to repair. | | Fully configured (directives + mode marker + standard directories; Scoped with valid scope) | Proceed with a **full review**. |

When is a project "LID-shaped"?

The coach treats a project as LID-shaped when **any one** of these is true:

• `docs/high-level-design.md` exists with non-trivial content.
• `docs/intent/` contains at least one `.md` file other than `README.md` or `index.md`.
• a `*-specs.md` file exists in the `docs/intent/` tree.
• `docs/arrows/index.yaml` exists.

The threshold is deliberately lenient. A populated arrow overlay is the strongest possible signal that a project is "doing LID"; if the instruction file uses a precursor name (e.g., *design-driven-dev*) or lacks the directive block entirely, that is *drift to surface*, not a reason to refuse coaching. Refusing to coach a visibly LID-shaped project is a false negative the coach was specifically designed to avoid — the user spent the effort to build the arrow; your job is to meet them there.

"Fully configured" is a *structural* check, not a *content* one. An empty-but-present HLD or LLD directory does not block coaching — content completeness becomes a finding, not a dispatch condition.

Detection rules

Use these exact signals:

• **LID directives**: `grep` for `"linked-intent-dev"` or `"Linked-Intent Development"` in the instruction file.
• **Mode marker**: `grep` for the `## LID` block's `- Mode:` bullet, with value `Full` or `Scoped` (case-insensitive, whitespace tolerated). Default Full when the block or bullet is absent.
• **Scope declaration**: the `## LID Scope` section in the instruction file, with include and optional exclude bullet lists.
• **Arrow-maintenance overlay**: `docs/arrows/` directory exists.

Inputs — what to read

Build the review from these sources:

• the instruction file — mode marker, scope declaration if Scoped, directive-block coherence.
• `docs/high-level-design.md` — section coverage, evidence of active intent vs. boilerplate, presence of implementation detail that belongs downstream.
• `docs/intent/*.md` — count (one per intent component?), granularity, alignment with HLD architecture, presence of history/changelog residue, presence of `[inferred]` markers in Decisions & Alternatives.
• the `*-specs.md` files in the `docs/intent/` tree — EARS format compliance, ID uniqueness and namespacing, status-marker usage, scope disambiguation hygiene, `{FEATURE}` prefix traceability to LLDs/HLD.
• **Sampled** code and test files — `@spec` annotation placement (entry-point convention) and coverage of behavioral specs. Do not attempt exhaustive reading; sample strategically.
• `docs/arrows/index.yaml` and arrow docs when the overlay is present — status markers and drift flags feed cascade-health findings.

**Sampling.** On a small project, sample by judgment: skim broadly and dig where the principles suggest dri