Linked Intent Dev

Linked-Intent Development

This skill guides a structured linked-intent development workflow. LID's goal is to narrow the agent's output distribution to the user's latent intent — specs, tests, and linkage together make the arrow of intent walkable, and the workflow's stops are where the agent's interpretation meets the user's intent for reconciliation.

Three rules govern every phase

Stop and iterate at every phase boundary. After completing each phase below, present the output to the user, incorporate numbered feedback, and proceed only on explicit approval. Each stop is mandatory. Skipping stops is the single most common way this workflow degrades into a rush — the discipline is non-optional. (Carveout: command-mode skills that execute a single directed pass, like /arrow-maintenance's audit-and-update, are not phase-structured in this sense and do not pause mid-pass. This workflow is generative; phases here produce intent, so every boundary gets a stop.)

Run a coherence pre-flight before starting or resuming implementation. When picking up work — new session, returning to a change, cascading from an upstream change — verify that the HLD, LLDs, EARS specs, and tests are mutually coherent for the segment about to be touched:

• Do the EARS specs trace to the current LLD?
• Do the tests trace to the current EARS specs?
• Does the LLD still reflect the HLD's architecture?

If drift is detected, fix the docs first, then implement. A resumption check prevents one session's drift from being compounded into the next session's change.

Write docs as their fresh author. Every HLD, LLD, and EARS spec produced by these phases must read as if authored fresh today, by someone who knew only the current intent and nothing of this conversation. As you draft or revise a doc, run the test on each line — would that fresh author put it on the page? Three residues fail it: narration of how the intent changed; meaning that only resolves for someone who was in this conversation; and answers or rebuttals that exist only because we discussed the question here. The keep-side is load-bearing too — rationale, considered alternatives, and constraints a fresh author would independently write stay; they are present intent, not residue. Record rejected alternatives and why in the LLD's Decisions & Alternatives table, not as asides in body prose. This is the docs carry current intent tenet. Write in the project's own domain language — name components, segments, and specs with the words the user and the codebase already use, not generic or LID-imposed labels. This is the Speak the project's language tenet.

Mode-aware triggering

Every LID project declares its mode in its instruction file (the project's AGENTS.md, or CLAUDE.md under Claude Code) under the ## LID block's - Mode: bullet. Defaults to Full if the block or bullet is missing or malformed (surface a one-line warning).

• Full LID: the skill triggers broadly — any prompt that could result in a code change is in scope.
• Scoped LID: additionally checks whether the files or subsystems the prompt touches fall within the declared scope. Scope is declared in the instruction file under a ## LID Scope section (see docs/intent/linked-intent-dev/core/core-design.md § Scope declaration format) with include/exclude glob patterns. If every file the prompt touches is outside scope (in the exclude list, or not in the include list), the skill does not trigger. If any touched path is in scope, the skill triggers. For prompts that reference no specific paths, default to triggering and ask the user to confirm when ambiguous. When the ## LID Scope section is missing or empty in a Scoped-mode project (misconfiguration), fall back to treating all prompts as in-scope and surface a warning suggesting /update-lid to declare scope.

The six phases

Phase 1 — HLD check (with bootstrap when needed)

First, check whether the project is LID-configured. If the instruction file has no LID directives AND no LID-shaped artifacts exist (no docs/intent/ content, no docs/high-level-design.md, no docs/arrows/index.yaml), this is a fresh project — the user invoked /linked-intent-dev with a description of what they want to build. Apply the update-lid skill's bootstrap branch as a sub-step: create docs/intent/, create or append-to the instruction file (AGENTS.md canonical, with a CLAUDE.md alias — see the update-lid skill) with LID directives, add the ## LID block (- Mode: default Full unless the user indicates Scoped, - Version: set to the installed linked-intent-dev version). Read the update-lid skill's SKILL.md if you need details on the bootstrap behavior; the bootstrap is the same skill called inline, not a separate workflow.

Once configured, proceed with the HLD check: does a top-level HLD exist at docs/high-level-design.md? Does it cover the domain of the change? If the change alters the project's architecture, update the HLD first. If no HLD exists (fresh project), draft one from the user's description.

For consequential architectural changes (a new approach, a significant trade-off, a new mode) — and on a fresh-project HLD draft — before committing to a full HLD sketch 2–3 competing options (~200 words each, naming downstream consequences) and present them for user selection. Surfacing decisions as choices among alternatives — rather than as the agent's best guess — is the primary edge-detection mechanism at the HLD level.

When drafting or revising the HLD, elicit tenets: surface the few decisions that could reasonably go more than one acceptable way, ask the user which way to lean, and record each as a one-line tie-breaker under ## Tenets. Apply the defensible-opposite test before proposing one — if the reverse of the tenet is absurd rather than a choice a different project could reasonably make, it is a platitude and resolves nothing; drop it. Apply a second test too: a tenet leans a class of decisions no spec anticipates — if the candidate reads as a triggered action (when X, do Y with a definite outcome), it is a spec, not a tenet; route it to EARS rather than the tenet list, even when its opposite is defensible. A tenet is edge detection for choices no spec will anticipate. Surface the load-bearing ones you can see and invite more; do not interrogate the user for an exhaustive set.

Whatever you draft, verify the HLD reads context-free: rationale present, alternatives named, no reliance on conversation context that won't travel to the next session.

See references/hld-template.md for standard HLD sections.

STOP for user review.

Phase 2 — LLD check or draft

Does a leaf LLD exist for the intent component being changed?

If not, draft one using the template at references/lld-templates.md.

The design layer is a recursive tree, and "HLD" and "LLD" are roles by position: the root is the HLD, the leaves are the LLDs that own EARS, and a component with enough internal depth to outgrow one doc is promoted to a sub-HLD — HLD-shaped for its subtree, owning no EARS of its own — with child components beneath it. Depth-2 (one HLD over a flat set of leaf LLDs) is the default; nesting is a triggered exception. So a single large LLD is a candidate for promotion to a sub-HLD, not automatically a smell — weigh promotion when a leaf outgrows itself rather than splitting reflexively.

When a node looks like it holds more than one thing, three shapes are possible, and which fits turns on the intent, not the size of the doc: if the parts share parent intent a parent doc should hold, promote to a sub-HLD over child leaves; if they are distinct intents with no shared parent, they are sibling leaves, each owning its own prefix; if they are merely categories of one intent — cross-cutting concerns (errors, security, performance, monitoring) or requirement types — keep one leaf and fold them into within-leaf <LEAF>-<TYPE> facets. The deciding test for promotion is whether the parent doc would carry real intent or just a table of contents: a categorical grouping is a taxonomy label, not a sub-HLD.

In complex projects multiple LLDs may look semantically relevant. Do not silently pick — surface the candidate leaf LLDs with their scopes and ask the user which applies.

If a leaf LLD exists, confirm coherence with the change and update as needed.

After drafting or substantially revising an LLD, run an LLD-level edge-case probe: a list of "what happens when..." questions pointed at this LLD's own gaps — missing state transitions, unstated invariants, unspecified API error shapes, ordering assumptions inside the component. (Cross-component and cross-spec interactions come later in Phase 4, not here.) When a subagent is available, delegate the probe to the subagent for cleaner, less-biased coverage. Present the gap list; the user triages which gaps to fix in the LLD vs. defer as open questions.

Verify the LLD reads context-free: the Decisions & Alternatives table has filled-out Rationale columns, alternatives considered are named, and the prose doesn't rely on assumptions only present in the conversation. A reader without your chat history should be able to follow the design.

STOP for user review.

Phase 3 — EARS spec draft or update

Every LLD change produces a corresponding EARS update. See references/ears-syntax.md for format.

• Spec IDs are stable. Revisions mutate text, not IDs, unless scope genuinely changes.
• Deleted IDs are not reused — git preserves the history.
• Delete specs that are no longer wanted rather than marking them obsolete.

After drafting or revising specs, run post-draft consistency verification:

• Coverage — are there behaviors described in the LLD that have no corresponding EARS spec?
• Contradiction — do any specs say different things about the same behavior?
• Implicit scoping — are any specs phrased as universal when they actually apply only to one context? When the current change adds a new mode or variant, audit sibling specs for scope that was implicit when only one variant existed. See references/ears-syntax.md § Scope Disambiguation for the litmus.
• Context-free reading — read each spec as if you have no conversation context. Are scopes explicit (no reliance on the surrounding section name to disambiguate)? Are conditions concrete (no "as we discussed" assumptions)? Specs travel by grep, so each line has to stand alone.

Present a brief consistency report alongside the specs.

STOP for user review.

Phase 4 — Intent-narrowing edge audit

Distinct from the Phase 2 LLD-level probe in what it targets. Phase 2 asked "what's under-specified in this LLD?" — structural gaps inside one component. Phase 4 asks "given the LLD + specs together, where could the agent's interpretation diverge from what the user meant?" The targets here are cross-spec and cross-segment:

• Interactions between this LLD's specs and a sibling segment's specs (who owns what state?).
• Specs that read cleanly in isolation but admit two different behaviors when composed with another spec in the same segment.
• Namespace or feature-prefix ambiguity (does spec X apply to mode A, mode B, or both?).
• Sequencing ambiguity across specs (if A and B are both required, does order matter?).
• Places where the user's latent intent is probably narrower than what the specs literally allow.

Ask the user to resolve these before tests are written. LID's fundamental purpose — narrowing the agent's output distribution to the user's latent intent — is carried by this step more than any other.

STOP for user review.

Phase 5 — Tests first

Write tests before the code that satisfies them, per the HLD's intent-preloading rationale.

• Tests carry @spec annotations citing the EARS IDs they verify.
• Place the @spec annotation on the test that directly exercises the spec's behavior, not on every inner assertion.
• Do not proceed to code until tests exist and fail in the expected way.

STOP for user review.