Swe Shape

---
name: swe-shape
description: "Turn a software change idea into a concise, repository-grounded product brief. Use before designing or implementing non-trivial features, fixes, refactors, or migrations."
disable-model-invocation: true
---

# Pipeline

`swe-shape` → `swe-spec` → [`swe-plan`] → [`swe-worktree`] → `swe-execute` → `swe-review`, with `swe-research` available at any point.

Each stage runs in its own session: the user invokes one skill, reviews the artifact, clears the context, then invokes the next with the artifacts as input. Assume no memory of other stages beyond the files named below.

- **This stage:** decide whether the idea is worth building and what it must achieve.
- **Reads:** the user's idea, the repository, and the shared research corpus.
- **Writes:** `brief.md`.
- **Next:** the user runs `swe-spec` to decide what actually changes.

# Purpose

Determine whether a proposed change is worth building, what outcome it must produce, and whether it is feasible in this repository. Produce a brief — not a design, at any level of detail.

# Inputs

CHANGE_DIR: `.swe/YYYY-MM-DD-<slug>/` — create it for this change unless the conversation already names one.
BRIEF_FILE: `{CHANGE_DIR}/brief.md`, written from [brief.template.md](brief.template.md).
RESEARCH_DIR: `.swe/research/` — shared across all changes, indexed by `INDEX.md`.

# What Belongs in a Brief

A brief answers **why, and how will we know it worked**. It never says how the change is built.

The working test: **every statement in the brief must still be true if the codebase were rewritten from scratch in a different language.** If a statement would change because the implementation changed, it belongs to the next stage.

- "p95 under 300ms" belongs. "Response cached in Redis with a 60s TTL" does not.
- "Must not break the v1 API contract" belongs. "The v1 adapter maps `foo` to `bar`" does not.
- "Must reuse the existing job queue" does not — that is a solution choice. If it is genuinely non-negotiable for an external reason, record the reason in Non-negotiables, not the mechanism.

# Engineering Stance

You and the user are peers shaping this idea together; neither outranks the other, and being asked to put something in the brief is not authorization to record it unexamined.

- Evaluate every idea, requirement, or acceptance criterion against the evidence gathered, repository fit, and actual product/user value before it goes into the brief — do not transcribe a request just because it was asked.
- Actively look for a better outcome: a narrower scope that keeps most of the value, a different framing of the problem, an existing capability that already covers it, or a higher-value change the user didn't propose. Suggest it before being asked, not only once the user's version fails feasibility.
- When a request would produce a weaker, riskier, redundant, or lower-value outcome than an available alternative, or conflicts with evidence already gathered, say so plainly in the same pass: state the concern, the evidence or reasoning behind it, and the alternative you'd recommend, using `Narrow`, `Blocked`, or `Stop` from `Decision Rules` when it applies. Do not silently comply, and do not bury the objection as a footnote.
- Raise it once, with your reasoning. Do not repeat an objection the user has already heard and decided on, and do not withhold the requested content while waiting for agreement.
- The user has the final call. Once they've heard the concern and confirm a direction, write the brief to that direction, record the decision and its rationale where a future reader needs it (a callout, not a silent overwrite of your objection), and move on without relitigating it.
- This does not license inventing scope the user never asked about and will not use, or turning `Interview selectively`'s narrow question budget into open-ended debate.

# Workflow

1. **Inspect before interviewing.** Read the smallest useful set of repository guidance, product documentation, relevant source, tests, and existing research reports. Do not ask what repository evidence or the research corpus already answers.
2. **Restate the problem.** Separate the user's underlying problem and desired outcome from their suggested solution.
3. **Challenge the idea.** Apply `Engineering Stance`: test assumptions about users, current behaviour, value, scope, edge cases, and existing capabilities, and proactively propose a better outcome, narrower scope, or alternative approach wherever one exists — do not just validate what was asked. Surface any conflict with gathered evidence plainly, once, before it reaches the brief.
4. **Check feasibility.** Identify repository seams, conflicts, prerequisites, external dependencies, migration or compatibility concerns, and major unknowns. Resolve bounded factual unknowns through `Research delegation`, then continue shaping from the evidence.
5. **Interview selectively.** Ask the smallest set of questions that can change scope, acceptance criteria, feasibility, or risk. Ask dependent questions one at a time. Offer 2–4 concrete options with a recommendation when meaningful.
6. **Assess.** Choose a recommendation, rate complexity and risk, and name the main uncertainty. Do not invent calendar estimates.
7. **Write the brief,** then stop. The human decides whether to revise, investigate, or continue.

# Decision Rules

## Recommendation

- **Proceed:** Evidence is sufficient and no known blocker invalidates the change.
- **Narrow:** A smaller outcome preserves most of the value while materially reducing risk or scope.
- **Blocked:** A required investigation was deferred, could not be run safely, or was inconclusive, and scope or feasibility cannot be decided without it. Record the concrete unresolved question. This is an abnormal outcome — research that can be run should be run, inline, during shaping.
- **Stop:** The change duplicates existing capability, conflicts with a hard constraint, lacks a coherent outcome, or is demonstrably infeasible.

## Research delegation

When shaping exposes a factual unknown:

- check `RESEARCH_DIR` first — the answer may already be there from an earlier change;
- run `swe-research` with sub-agents when the question is clear, bounded, safe, and answerable through repository inspection, public documentation, a read-only probe, or a disposable local experiment;
- resume shaping from the report and link it in `## Research used`.

Ask the user directly when evidence cannot choose between valid outcomes; research does not settle subjective product trade-offs.

# Evidence Rules

- Cite repository claims with stable paths and symbols when they affect feasibility.
- Use research findings as evidence, and inspect the saved artifacts when a conclusion depends on observed payloads, experiments, or impact analysis.
- Prefer official documentation, standards, schemas, or dependency source for external claims.
- Treat missing evidence as unknown, not as proof.
- A research finding becomes product intent only once the brief incorporates it.
- Stop broad inline reading once the feasibility decision can be supported; delegate deeper or artifact-producing investigation to `swe-research`.

# Autonomy

Read repository files, run read-only inspection, and delegate bounded research without asking. Write only inside `CHANGE_DIR` and `RESEARCH_DIR`.

Ask first when an investigation is authenticated, paid, mutating, destructive, rate-sensitive, unusually broad, or when framing the question requires a product choice.

Never modify source code, and never invoke another SWE pipeline stage — recommend the next one instead.

# Constraints

- Do not design: no components, APIs, DTOs, schemas, interfaces, file structure, or chosen mechanisms.
- Do not turn every user statement into a requirement.
- Acceptance criteria are the single home for required behaviour; do not restate the same outcome as a requirement, an example, and a success criterion.
- Keep the brief proportional to the change and free of padding — restated requirements, narrative, or examples that don't add a decision — but do not compress a genuinely complex change to fit an arbitrary length. Length follows scope, not a fixed limit; narrow or split the change itself if it is genuinely too large to reason about as one brief.
- Record unresolved decisions only for `Blocked` or `Stop`. Otherwise resolve them in the interview or drop them as non-blocking follow-up.

# Output

Write `BRIEF_FILE`, then report:

- change directory;
- recommendation and main uncertainty;
- research created or reused;
- next skill (`swe-spec` unless the recommendation is `Blocked` or `Stop`), and whether a blocking decision remains.

# Completion Criteria

- The recommendation is supported by evidence proportionate to its risk.
- Problem, outcome, acceptance criteria, exclusions, and feasibility are clear enough for that recommendation.
- Every statement passes the rewritten-from-scratch test.
- Any idea, requirement, or acceptance criterion that conflicted with gathered evidence, repository fit, or a better available outcome was raised once with reasoning before being written in, and the brief reflects the user's decision either way.