ie-plan-assist

name	ie-plan-assist
description	Inject intent-engineering principles into the planning phase — surface the least-astonishment, convention, simplicity, and UX considerations relevant to the work being planned, as a tailored advisory checklist. Lightweight and non-blocking; use while drafting a plan or thinking through an approach, before a full plan doc exists. For validating a finished plan, use ie-validate-plan instead.
argument-hint	[a short description of what's being planned, or blank to use the current conversation/plan context]

Intent Engineering — Planning Assist

A fast, advisory pass that brings the principles to the table while you plan, so the design starts intuitive instead of being corrected later. It does not fan out a heavy review or score anything — it emits a tailored checklist of the considerations that matter for this work, drawn from the principle docs.

When to use

• Drafting an approach or a plan, before a finished plan doc exists.
• Deciding between designs and wanting the principle trade-offs surfaced.
• As a planning-phase companion (a planning workflow can call this to enrich a draft).

For a finished plan/spec doc, use ie-validate-plan. For code, use ie-review.

How it works

This skill runs inline (no sub-agents by default — it's meant to be quick and conversational). Steps:

1. Establish the subject. Use the argument, or the current plan draft / conversation, to state in one line what's being planned and identify the surface(s): backend logic, public API/interface, framework/stack, user-facing UI, data/config.

2. Select the relevant principles. Read only the docs that apply (from ${CLAUDE_PLUGIN_ROOT}/resources/ — see references/principle-index.md):

   • Always: principles/least-astonishment.md, principles/occams-razor.md.
   • API/interface or naming decisions: agnostic/api-design.md, agnostic/naming.md, agnostic/error-handling.md, principles/dwim.md.
   • Framework/stack chosen: the matching frameworks/<stack>.md + principles/convention-over-configuration.md + agnostic/defaults-and-configuration.md.
   • User-facing surface: principles/human-interface-guidelines.md, principles/ux-design.md, principles/look-and-feel.md, agnostic/accessibility.md, agnostic/information-architecture.md.

3. Emit a tailored checklist, grouped by lens, of the concrete decisions to get right up front. Each item is a question or guard specific to the subject — not a generic principle restatement. Examples:

   • Predictability: "Name the new endpoint after what it does — will GET /accounts/:id/summary ever mutate? If caching, make the write explicit."
   • Convention: "This is Rails — model the cancellation as a RESTful sub-resource (DELETE/nested resource), not a custom cancel action, unless the repo already does custom actions."
   • Simplicity: "You're adding a strategy interface for one payment provider — defer it until the second provider is real (YAGNI)."
   • Experience: "List the states for the new filter: loading, empty, error, no-match — and the keyboard path. Decide them now, not in code review."

4. Surface tensions, don't resolve them. Where principles conflict for this work (DWIM forgiving-input vs least-astonishment; convention's structure vs YAGNI), name the trade-off and let the planner choose. Read ${CLAUDE_PLUGIN_ROOT}/resources/principles/software-philosophies.md "Tensions".

5. Optional deepening. If the user asks for more rigor on a specific surface, offer to spawn the matching lens (ie-*-reviewer) in Context: plan-assist against the draft for a focused advisory pass. Only on request — the default is the inline checklist. That spawn uses the plan-assist exception in the subagent template: the lens writes no artifact and returns an advisory note (prose allowed), not JSON — so this skill still writes nothing to disk and the "no sub-agents by default" promise holds (a sub-agent runs only on explicit request, and even then produces no file).

Output

A short markdown checklist grouped by lens (Predictability / Convention / Simplicity / Experience — include only the lenses that apply), plus a Tensions note if any. Every item is specific to the subject and phrased as a decision to make now. Advisory only — nothing blocks, nothing is written to disk unless the user asks to save it.

Keep it tight: the value is a focused list of the right questions, not an essay.

---

Reference files (read at runtime)

Depends on ${CLAUDE_PLUGIN_ROOT} resolving (standard in Claude Code):

• ${CLAUDE_PLUGIN_ROOT}/references/principle-index.md — principle → doc → lens map
• ${CLAUDE_PLUGIN_ROOT}/references/lens-catalog.md

Principle docs to read selectively live under ${CLAUDE_PLUGIN_ROOT}/resources/.