jszmajda/lid/lid-coach

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:

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 drift. When the project has more than 15 LLDs or more than 200 files carrying `@spec` annotations, or when docs/arrows/index.yaml exists, read references/sampling.md before reading inputs: it says how to sample complete arrow paths and how the overlay's index guides where to look.

How to run the review

1. Dispatch. Apply the table above. If coaching cannot proceed, stop and explain.
2. Read inputs. Read the instruction file, the HLD, every LLD, every spec file, and a strategic sample of code + tests. When the overlay is installed, read index.yaml and arrow docs.
3. Reason with principles. For each review dimension below, compare what you see to the principle's audit signals. Collect findings.
4. Cold-read pass through every LID doc. Beyond the dimension-by-dimension review, do one pass through every LID doc as if you have no conversation context at all — no memory of prior chats, no awareness of what "of course" or "as we discussed" might refer to. Future sessions read these docs cold, so the doc must stand on its own without the conversation that produced it. Surface anything unclear, ambiguous, or evidently dependent on context that isn't on the page. The unclear bits are either lost implicit context (state that lived only in the author's chat session and never got written down) or just writing worth tightening — either way, surface them. Do not reduce this to grepping for specific phrases; that misses the deeper pattern.
5. Decisions-table sweep. After the dimension pass, revisit every Decisions & Alternatives row you read, with its design doc and the docs above it in hand (the doc tree is what a cold reader gets). First ask: would a cold reader of the landed design still question this choice, or want to reverse it? Most rows stop there and pass, however terse: a parameter whose source is named, a choice the HLD's tenets or Approach already explain, a choice whose alternative and cost are evident from the choice itself. Only for a row that a reader would question, ask: can they reconstruct what was given up and what cost was accepted? A row that fails that is a decision-capture finding (dimension 18).
6. Prioritize. High-priority findings are those that block the arrow from being walkable (missing phases, broken linkage, misconfigured scope) or compound over time (accumulation antipatterns, LLD under-specification, implicit-context leaks in load-bearing docs). Medium-priority findings weaken coherence without breaking it. Low-priority findings are quality-of-life improvements.
7. Produce the report. Render inline; do not persist to disk unless the user asks.
8. Stop. The coach does not iterate. The user reads, decides, and acts.

Trust the declared intent

The coach evaluates drift relative to what the project declared it is, not against a fixed template.

• In Scoped mode, paths outside the declared scope are not reviewed and not gaps. List them in the out-of-scope section.
• In Scoped mode, HLD sections marked "not yet specified" are intentional — do not flag them.
• A Full-mode project with an empty docs/intent/ directory has not yet authored any LLDs; flag this only if there is observed behavior that should have an LLD (an LLD gap), not because the directory is empty.

Do not nag about shape choices the project has deliberately made. The coach's job is to surface drift relative to declared intent, not to enforce a canonical shape against the user's wishes.

When the user asks how to use LID

If /lid-coach is invoked with a question about using LID rather than a request for a review, or the user takes the report's second invitation, do not run or re-run the review. Read references/conversational-guidance.md and references/lid-faq.md, and engage conversationally.

LID principles — the body of theory this skill reasons from

The coach applies these principles as lenses during review. Each principle below carries three parts the coach uses when constructing findings:

1. A short description — what the principle says.
2. A why it matters layer — what the principle protects against, what compounds if it's ignored. This is the answer the coach draws on when a finding needs to teach, not just correct.
3. An audit signal — what drift from the principle looks like in a real project.

Cite principles in findings by name (e.g., "mutation, not accumulation") — not by anchor or numeric ID. Always pair the name with a plain-English gloss inline so a reader new to LID can follow.

These principles are a downstream artifact of LID's own high-level design. When LID's HLD changes, this body cascades via the standard LID-on-LID workflow.

Foundational

• Intent leads; code is compiled output. Specs are the source of truth; code is the compiled result. Code may be regenerated from specs — the reverse is not supported. Why it matters: when spec and code disagree, updating the spec to match the code hides the drift — the system pretends intent changed when really implementation did. The gap compounds session over session, and eventually the project loses the ability to reason about its own behavior at the spec level. Audit signal: code that contradicts specs without either being flagged or updating the spec; specs that are written to describe code after the fact rather than drive it.