Idea: shape intent before criteria

Turn an idea or feature request into a settled, agreed problem and scope. The output is shared understanding plus a short artifact the acceptance-criteria stage can consume. This phase explores and converges; it does not specify.

Checklist (do in order)

1. Explore context files, docs, recent commits, and whether this is an existing project: look for docs/specs/overview.md (or root specs/overview.md — an existing root tree stays in use, the back-compat rule in getting-started), a constitution.md, and a CONTEXT.md.
2. Set level, then tier. level: project (clean repo, no overview/constitution, so you are shaping a whole app) or feature (existing project, so you are shaping one piece). Then tier: if this is a small self-contained change (tens of lines, no new runtime dependency, no new public API, no new trust or process boundary), stop and run /agent-sdlc:light instead. Do not continue this skill. Full chain only if the user asked for it or a trigger fired. When unsure, hand off to light. depth (vague vs specific) scales step 4 only when you stay on the full chain.
3. Scope-check / decompose if the ask spans several independent pieces, flag it and decompose. At project level this decomposition is a main output (the feature list). At feature level, if it is really several features, split and shape the first.
4. Diverge propose 2-3 approaches with tradeoffs, leading with your recommendation and why. Heavy for a vague idea, light for a specific feature. If the candidate approaches would land better drawn than described, read visual-aids now and apply it here: it is the load-bearing visual-aid discipline.
5. Grill to converge interview one question at a time, walking down the decision tree and resolving dependencies between decisions one by one. Give a recommended answer with every question. Prefer multiple-choice. If the codebase can answer it, explore the code instead of asking.
6. Keep terminology sharp (throughout step 5) sharpen fuzzy or overloaded terms into a single canonical term, challenge anything that conflicts with the glossary, stress-test relationships with concrete scenarios, and cross-check the user's claims against the code.
7. Capture inline (as terms/decisions resolve, never batched) update CONTEXT.md (glossary only, no implementation detail), and offer an ADR only when the decision is hard to reverse AND surprising without context AND a real tradeoff. Flag any conflict with the constitution immediately.
8. Settle and write the artifact present the settled problem, scope, non-goals, chosen approach, and resolved decisions in sections scaled to complexity, and get approval. Where it lands depends on the level (see Two levels): a feature writes the ## Brief section of docs/specs/<feature>/<feature>.md and appends the feature to overview.md's feature list; a project writes the ## Overview section of docs/specs/overview.md and seeds root-level constitution.md and CONTEXT.md. Either way, the spec is process record — it lives in the spec tree, apart from the repo's product documentation pages.
9. Hand off for a feature, tell the user it is ready for the acceptance-criteria step. For a project, hand back the feature list and offer to shape the first feature next (its own docs/specs/<feature>/<feature>.md pass). Do not start the next step yourself. If Linear sync is enabled in .agent-sdlc/config.json, also perform this stage's action via the linear-sync skill.

Principles

• One question at a time. Multiple-choice when you can; always give your recommended answer (the system-wide recommend-and-alternatives rule).
• Code over questions. If the codebase answers it, go look instead of asking.
• YAGNI. Cut anything the problem doesn't actually need.
• Terms before details. A decision phrased in fuzzy language isn't resolved.
• Loop when grilling exposes a fuzzy problem. Drafting a decision often reveals the framing wasn't settled; go back, re-settle, then continue.
• Recommend, don't just ask. Every open question carries your proposed answer and why.

Done when

• You can state the problem and scope in a few crisp sentences.
• The terms in play are canonical and captured in CONTEXT.md.
• Every key decision is resolved, or explicitly deferred with the reason.
• The user has approved the settled artifact.

The artifact (output)

A short file containing only:

• Problem / intent
• Scope & non-goals
• Chosen approach and why, over the alternatives considered
• Resolved key decisions
• Glossary terms touched
• Any ADRs

No requirements, no success criteria, no design detail. Those are the next stage. This content is the ## Brief section of docs/specs/<feature>/<feature>.md. At project level the same shape is the ## Overview section of docs/specs/overview.md, plus the feature decomposition (the list of features the project breaks into).

Two levels: project vs feature

The same skill runs at two scopes, decided in step 2.

Project (clean repo, "I want to build an app for X"): you are shaping the whole project. Outputs are the north-star plus the breakdown into features:

• docs/specs/overview.md ## Overview problem, scope, overall shape, and the feature decomposition
• constitution.md (root) standing principles, seeded here
• CONTEXT.md (root) the initial glossary

A project pass ends by handing over the feature list; each feature is then its own feature-level pass.

Feature (existing project, "I want to add X"): you are shaping one piece:

• the ## Brief section of docs/specs/<feature>/<feature>.md — this feature's settled intent (later joined by the ## Acceptance Criteria, ## Design, ## Tech Stack, and ## Plan sections in the same file).

Layout:

/
├── constitution.md          ← standing principles (project-wide)
├── CONTEXT.md               ← glossary (project-wide)
└── docs/specs/
    ├── overview.md          ← project tier: ## Overview · ## Architecture · ## Tech Stack
    ├── adr/                 ← decision records
    └── <feature>/
        ├── <feature>.md     ← ## Brief (here) · ## Acceptance Criteria · ## Design · ## Tech Stack · ## Plan
        └── gate-report.md   ← gate output

A repo that already has a spec tree at root specs/ keeps using it — the back-compat rule in getting-started (never split a repo across both locations, never auto-migrate); new spec trees are created at docs/specs/.

Conventions

• CONTEXT.md is a glossary and nothing else, devoid of implementation detail, not a spec or scratchpad. It lives at the repo root (canonical vocabulary the whole repo shares). Create it lazily, when the first term is resolved.
• ADRs live under docs/specs/adr/ (beside the spec tree, wherever it lives) and are created only when the three-part test above is met.
• If a CONTEXT-MAP.md exists at the root, the repo has multiple contexts; resolve terms in the context they belong to.
• Keep the trigger distinct from any brainstorming skill you may also have installed, so this one fires when you mean to run the Agent SDLC pipeline.