# Shape a founder request into a reviewed intent record and spec items

Roles:

- Analyst
- Reviewer

The founder supplies one request in their own words.
Planning and design happen in one sitting: `shape` turns the request into one intent record under `specs/intents/` and the spec items it adds or changes under `specs/packages/`, reviews them, and commits them together.
Until review ends, the drafts travel as text in Analyst's replies and no player changes the repository; only the final step writes the files, and the intent record and the spec items land in exactly one commit on the current branch.
There are at most two review rounds.
Captain shall use the repository-effect receipt as the authoritative identity of that commit.

### SHAPE-1

If Analyst asks the founder clarifying questions, the founder's answers continue this same behavior.

When the founder gives a request, Captain shall prompt Analyst:

> Shape the founder's request below into one intent record and the spec items it needs.
> Read @specs/map.md and @specs/meta.md first, then the specs under @specs/packages and the code they govern that the request touches.
> Before drafting, ask the founder at most two clarifying questions, together in one message, and only where the answer changes the goal, the constraints, or the acceptance checks; if the request is clear, ask none.
> Draft one new intent record for @specs/intents in the form @specs/meta.md requires for intent records, with the next free record number, stating the goal, the constraints, and the acceptance checks; give each acceptance check an observable pass condition.
> Draft every spec item the request adds or changes under @specs/packages in the GEARS form @specs/meta.md requires: one requirement per item, no item restating or contradicting an existing one.
> Do not create, edit, or delete any file, and do not commit; the drafts are written to the repository only after review.
> Reply with the complete drafts: the intent id; for each new file, its path and its complete content in a fenced block; for each existing file, its path and every item you add or change in full, each with its id and where it goes, plus the ids of any items you remove.
>
> > Founder request: <caller-input>

Results:
- `drafted`: Analyst replied with the complete drafts and changed no file. Output shall include `analystOutput: <verbatim final text>`.

### SHAPE-2

When the first review round begins after Analyst replies with the complete drafts, Captain shall prompt Reviewer:

> Review the intent record and spec items Analyst drafted for the founder's request below; the complete drafts are in Analyst's reply below, and none of them is in the repository yet.
> Read @specs/meta.md and the existing specs the drafts touch.
> Check that every spec item states exactly one requirement in the GEARS form @specs/meta.md requires.
> Check that every acceptance check in the intent record is testable: an observable pass condition, not an aspiration.
> Check that no drafted item contradicts or restates an existing spec item, and that the drafts cover the request without adding requirements it does not ask for.
> Flag only what materially affects these checks — not style or equally valid wording.
> Number your findings and cite the file and item id of each.
> Do not edit files or commit; report findings only.
> If nothing material remains, say plainly that you have no findings.
>
> > Founder request: <caller-input>
> > Analyst drafts: <analyst-output>

Results:
- `hasFindings`: Reviewer raised one or more findings. Output shall include `reviewerOutput: <verbatim final text>`.
- `noFindings`: Reviewer affirmatively reported no findings; a progress report or promise of a later review supports no outcome.

### SHAPE-3

When Reviewer raises findings in the first review round, Captain shall prompt Analyst:

> Fix the Reviewer's findings below in your drafted intent record and spec items, quoted below.
> Fix each finding at its root, and every other instance of the same defect in the drafts.
> If a finding would contradict the founder's answers or an existing spec item, leave it unfixed and explain why.
> Do not create, edit, or delete any file, and do not commit; the drafts are written to the repository only after review.
> Report how you handled each finding, then reply with the complete revised drafts in the same layout as before: the intent id; for each new file, its path and its complete content in a fenced block; for each existing file, its path and every item you add or change in full, each with its id and where it goes, plus the ids of any items you remove.
>
> > Founder request: <caller-input>
> > Analyst drafts: <analyst-output>
> > Reviewer findings: <reviewer-output>

Results:
- `fixed`: Analyst replied with its dispositions and the complete revised drafts and changed no file. Output shall include `analystOutput: <verbatim final text>`.

### SHAPE-4

When the second review round begins after Analyst has handled the first round's findings, Captain shall prompt Reviewer:

> This is the second and last review round of the intent record and spec items drafted for the founder's request below; the complete revised drafts and Analyst's dispositions of your earlier findings are in Analyst's reply below, and none of the drafts is in the repository yet.
> Accept or challenge each of Analyst's dispositions.
> Check that every spec item states exactly one requirement in the GEARS form @specs/meta.md requires.
> Check that every acceptance check in the intent record is testable: an observable pass condition, not an aspiration.
> Check that no drafted item contradicts or restates an existing spec item, and that the drafts cover the request without adding requirements it does not ask for.
> Flag only what materially affects these checks — not style or equally valid wording; do not raise again a finding Analyst rejected with sound reasoning.
> Number your findings and cite the file and item id of each.
> Do not edit files or commit; report findings only.
> If nothing material remains, say plainly that you have no findings.
>
> > Founder request: <caller-input>
> > Analyst drafts: <analyst-output>

Results:
- `hasFindings`: Reviewer raised or kept one or more findings. Output shall include `reviewerOutput: <verbatim final text>`.
- `noFindings`: Reviewer affirmatively reported no findings; a progress report or promise of a later review supports no outcome.

### SHAPE-5

When Reviewer reports no findings in either review round, Captain shall prompt Analyst:

> Review found nothing further in your drafted intent record and spec items for the founder's request below.
> Write the drafts quoted below into the repository exactly as drafted, and update @specs/map.md if it must index a package you add.
> Run `npx @sublang/spex lint` and fix only what it reports in the files you wrote.
> Commit those files in exactly one new commit on the current branch; commit nothing else and never amend or rewrite an existing commit.
> Follow the repository's commit conventions; make the message say what the intent is and which spec items it adds or changes.
> Report the commit hash and the intent id to the founder.
>
> > Founder request: <caller-input>
> > Analyst drafts: <analyst-output>

Results:
- `committed`: Analyst made one new commit holding the intent record and the spec items. On this outcome the workflow returns the commit as latestCommit and the intent id as intentId. Output shall include `latestCommit: <commit identity>` and `intentId: <intent id>`.

### SHAPE-6

When Reviewer raises or keeps findings in the second review round, Captain shall prompt Analyst:

> The second and last review round of your drafted intent record and spec items for the founder's request below still raised the findings quoted below; there is no further review round.
> Fix each finding in the drafts at its root, and every other instance of the same defect.
> If a finding would contradict the founder's answers or an existing spec item, leave it unfixed and explain why.
> Write the fixed drafts into the repository, and update @specs/map.md if it must index a package you add.
> Run `npx @sublang/spex lint` and fix only what it reports in the files you wrote.
> Commit those files in exactly one new commit on the current branch; commit nothing else and never amend or rewrite an existing commit.
> Follow the repository's commit conventions; make the message say what the intent is and which spec items it adds or changes.
> Report the commit hash and the intent id to the founder, and state plainly which of these last fixes no reviewer has seen.
>
> > Founder request: <caller-input>
> > Analyst drafts: <analyst-output>
> > Reviewer findings: <reviewer-output>

Results:
- `committed`: Analyst handled the last findings and made one new commit holding the intent record and the spec items. On this outcome the workflow returns the commit as latestCommit and the intent id as intentId. Output shall include `latestCommit: <commit identity>` and `intentId: <intent id>`.
