jszmajda/lid/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 it — the phase output in full, or an authorized inspector's summarized findings (see Specification and inspection instruments below) — incorporate numbered feedback, and proceed only on explicit approval. Each stop is mandatory; the stops are the mechanism realizing the HLD tenet Every phase is inspected. Skipping stops is the single most common way this workflow degrades into a rush. (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 — unless the user has expressly authorized a consolidated cadence: a warned override, or an opt-in experiment they have declared.)

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.

Specification and inspection instruments

Two kinds of intent work run through the phases, verified differently: specifying (Phases 1–3: turning latent intent into written spec — checked against what the user actually meant) and inspecting the cascade (the stops and the Phase 4–6 checks — checking downstream rungs against the spec). Each admits more than one instrument; offer the choice conversationally. There is no configuration for it (see docs/decisions/inspection-instrument-selection.md).

Specifying — follow the user's grain. Drafting-then-review works one document at a time: draft the artifact whole, the user reviews it whole. Elicitation works one concept at a time: raise a single aspect, the user responds to just that, and the document accretes from the answers. Match the user's current grain — a user who answers one aspect of a draft and ignores the rest is asking for elicitation; whole-document feedback means draft-review is working. Switching mid-artifact is normal. When eliciting: one aspect per exchange, real tradeoffs with concrete examples, confirm understanding before recording a choice, and keep it short — an easy-to-click menu that hides the real decision is worse than no menu.

Inspecting — the user chooses the inspector. Default: the user reads each phase's output at its stop. On the user's authorization: a zero-context reader (given only the arrow artifacts, never the conversation, so it cannot inherit the builder's blind spots — the coach's cold-read pass and the experimental blind differential are this family) or a delegated inspector (a subagent reviewing the phase output in the user's place). Inspection may also be relocated out-of-band: the user lands the change on a branch and leans on the project's existing review process (a pull-request review). Relocation is scoped to what the review will actually read — a code-focused review covers only the code rungs, so the intent phases keep their full in-session ruling unless the review explicitly covers the intent artifacts. The stops still run in-session, and a review finding that reveals an intent gap walks the arrow like any bug.

Three rules hold whatever the instruments:

• A delegated inspector's findings are never applied silently — present them summarized and focused at the stop; a pass means "no counterexample found," not proof. On a clean pass, name where the inspector looked hardest and offer the user a spot-check of that raw output — ruling on a clean pass means sampling, not ratifying an empty report.
• A spec or draft that admits more than one reading always goes back to the user — only they hold the latent intent — at whatever phase the fork is discovered, before further tests or code land against either reading. A fork found after tests exist is surfaced with the affected tests named.
• Delegation changes who inspects at a stop, never how many stops there are. The user can still override anything, per the user is always right — with warning.

Judgment still reaches the user, however inspection is set up. Judgment is what the user brings to the pair. When they delegate inspection, consolidate stops, lean on out-of-band review, or let work run largely on its own, the moments that need their judgment still happen; they just stop being shown by default. So when you meet one, bring it to them at that phase's stop, or right away if you cannot proceed without it. Do not settle it on their behalf, and do not leave it buried in an inspector's findings.

These kinds come up often. The list is not complete: any call that is recognizably the user's (a preference, a priority, a risk only they can weigh) goes to them too.

• Spec fork: a spec or draft admits more than one reading.
• Unsettled choice: the change needs a decision no document makes.
• Tenet or goal conflict: a mechanism works against one of the project's own tenets or goals.
• Cross-node contradiction: two design nodes say incompatible things.
• Rung mismatch: an EARS spec says more or less than its design node.
• Code drifts from spec: code or tests do something no spec says, or miss something one does.
• Missed cascade: an upstream change leaves downstream intent stale.
• Wrong attachment level: a decision or term sits below some of the nodes that use it.
• Under-captured decision: a choice a cold reader would question has no record they could reconstruct it from.
• Hard to undo: the change moves or deletes data, migrates a schema, or has an external effect that cannot simply be reverted.
• Unpinned invariant: a rule the design depends on has no test (or proof) holding it.

By default, bring all of these to the user; when unsure, ask. The user decides how much of this they want to check, based on the risk as they see it. A tool that handles their money may need everything checked; a game made for fun may need very little. They usually say so in conversation, sometimes as prose in their instruction file. Follow what they said, and keep it to the work they said it about: letting some judgment go for a research prototype does not carry over to the product it will join. If you notice a pattern, such as them waving through every cascade question, name it and ask whether to treat it as their preference; do not start applying it on your own.

Spec forks and hard-to-undo changes need more than that. Treat either as let go only when the user says so about that kind specifically, never because they want fewer interruptions in general.

Capability flags — bring the user in where your model is known to miss things. references/capability-flags.md lists kinds of judgment that eval evidence shows some models reliably miss at a given reasoning effort. Check whether a flag applies to you by placing yourself in its lookup as the file directs: by the model your harness or the user names, never by your own sense of which model you are; with no row of your own, by a tested earlier or smaller relative's row; and if nothing places you, treat every flag as applying. When a phase's work touches a flagged area, do your best work there as usual, then at that phase's stop name the area and what the user should check — e.g., "Please check this LLD's mechanisms against the HLD tenets yourself; models configured like me are known to miss contradictions like that." Send that judgment to the user even if they have authorized another inspector at that stop, because an inspector running on the same model has the same gap, and even if they had let that kind of judgment go, telling them why. If they have seen the flag and still prefer to let it go, follow that. Say it once, plainly — it routes one judgment to the user; it does not qualify the rest of your work. If the file lists a tendency for your configuration (a lean in something the user already decides, such as offering decision docs too readily), mention it once when that behavior comes up. When no flag applies to you, including when the file lists none, say nothing about capability flags.

Delegation discipline

Discipline does not travel by ambient context. A subagent dispatched to perform phase work receives only its prompt — not this skill, not the instruction file, not the conversation. Embed the phase's obligations in the dispatch prompt itself.

For implementation work (Phases 5–6): the EARS spec ID(s) in scope, the tests-first gate ("write failing tests first; do not proceed to code until they fail as expected"), and the @spec annotation requirement. For a Phase 2 probe: what the probe targets. For a delegated inspector: the spec(s) it inspects against and the requirement to return summarized, focused findings. For every dispatch, whatever the phase: the obligation to surface, not resolve, ambiguity — a spec that admits more than one reading comes back as a question, never as a silently chosen reading. A dispatched agent that itself dispatches carries these obligations into its own dispatch prompts — the rule travels with the work. When a phase gains a new obligation, dispatches of that phase's work carry it.

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