Memo Clarification Loop

Workflow

agent starmemo

Signature conventions

All names follow the conventions loaded at bootstrap (starspec/agents/conventions/memo-naming). Quick reference:

Actions: kebab-case-imperative — e.g. create-order
Events: kebab-case-past-tense — e.g. order-placed
Operations: kebab-case — e.g. get-order
Errors: kebab-case-noun-phrase — e.g. order-not-found

Signatures use a light typed style:

create-order(userId: string, items: Item[]) → OrderId
get-order(orderId: string) → Order

Events carry a typed field list:

order-placed: { orderId: string, userId: string, total: number, timestamp: Date }

If a signature is partially unknown, write (?) for unknown parts — these become [ERROR] or [SCOPE] gaps in Open Questions.

These signatures feed directly into \{% action %\}, \{% operation %\}, \{% event %\}, and \{% error %\} tags during scaffold mode.

Gap taxonomy

Every item in ## Open Questions must carry exactly one tag:

Tag	Meaning
`[SCOPE]`	Feature boundary is unclear — could be one or multiple features
`[NAMING]`	Term is ambiguous or conflicts with another term in the document
`[DOMAIN]`	It is unclear which domain owns this entity, action, or event
`[ERROR]`	A failure path or error case is not described
`[FLOW]`	A flow step is implicit, skipped, or only partially described
`[UI]`	An interaction is mentioned but the UI pattern is unspecified
`[POLICY]`	A business rule is implied but not stated explicitly
`[NFR]`	A non-functional requirement (performance, security, access) is missing
`[ACTOR]`	An action is described but no role is attributed to it

Proposal rules

An item belongs in ## Proposals (not ## Open Questions) when:

It is not stated in the source but is strongly implied by what is described, or
It is standard for this class of application and its absence is a likely oversight

Every proposal must include a one-sentence reason. Examples of valid proposals:

A password-reset flow when authentication is described but account recovery is not mentioned
A soft-delete policy when deletion is mentioned but data retention is not
An admin role when configuration or moderation actions appear without a named actor
Standard CRUD error cases (not-found, already-exists, unauthorized) for any entity with create / update / delete operations
A session or token entity when login is described without a persistence model
A confirmation step in a flow when a destructive or irreversible action is described

Clarification Loop

After writing the PreSpec, begin the interactive clarification session. Work through one category at a time in this fixed order. Update the PreSpec file in place after each round — fold confirmed answers into the relevant section and remove resolved items from ## Open Questions.

Bundle related questions in a single message when they concern the same subject (e.g. the scope and role attribution of a single feature, or the name and ownership of a single entity). Do not mix categories across rounds.

Round 1 — Feature inventory

Open with a summary:

“I found {n} features: {comma-separated list}. Are these at the right granularity, or should any be merged or split?”

Then step through each feature, bundling scope and role questions together:

“{feature-name}

Scope: {scope sentence} — does that match your intent?

Roles: I attributed this to {role list} — correct?”

Round 2 — Domain grouping

Present the domain list with features and entities mapped to each:

“I grouped things into these domains:

{domain}: owns {entity list}, covers {feature list}

…

Does this breakdown make sense, or should anything move?”

Flag any entity or action that could belong to more than one domain — the user must pick one owner before proceeding.

Round 3 — Actions, events, and operations

For each domain, present the drafted signatures and ask for corrections:

“{domain} — I extracted these API items:

Action: {signature} — correct name and shape?

Event: {EventName}: { fields } — complete?

Operation: {signature} — correct?

Any renames, missing parameters, or return types to fix?”

Also ask about any (?) placeholders in signatures at this point.

Round 4 — Naming & terminology

For each [NAMING] gap:

“You used both {term A} and {term B}. Should these be the same concept or two distinct things?”

For each term in ## Terminology:

“Should {term} become a formal glossary entry under domain {domain}?”

Apply confirmed names retroactively across the whole PreSpec before moving to Round 5.

Round 5 — UI scope

For each [UI] gap and every flow that implies a user interaction:

“For {flow-name}: should this include a standard {form / list / detail / modal} UI, or is the backend behaviour sufficient for now?”

Round 6 — Errors, policies, and proposals

First work through [ERROR] and [POLICY] gaps from the source:

“What should happen when {condition}? Is this a hard error, a soft warning, or a silent automatic policy?”

Then, if ## Proposals is non-empty, introduce them:

“I also have {n} proposals for things not mentioned in the memo but commonly needed for this type of application. Shall I walk through them?”

Present each proposal in a group when proposals are related (e.g., a set of standard CRUD errors for the same entity):

“Proposals for {entity/feature}:

{item A} — Reason: {why}

{item B} — Reason: {why}

Accept all, accept individually, or decline?”

Accepted proposals move from ## Proposals into the appropriate section and are recorded as [ACCEPTED] in the hand-off summary.
Declined proposals are struck through in ## Proposals and recorded under “Declined proposals” in the hand-off summary.
Modified proposals are accepted with the user’s amended wording.

Round 7 — NFRs

If no NFRs were extracted from the memo:

“No performance, security, or access constraints were mentioned. Should I infer standard defaults (authentication required, no PII logging, p95 < 2 s response time) or leave NFRs open for now?”

Hand-off

When ## Open Questions is empty or the user says “good enough”, present a summary:

“The PreSpec is complete:

{n} features confirmed

{m} domains defined with {k} actions, {j} events, {p} operations

{q} proposals accepted, {r} declined

{s} open questions resolved

Ready to run scaffold from docs/{name}.prespec.md?”

If yes, hand off to starscribe scaffold mode using the PreSpec as the source file. Because the PreSpec is already structured, Phase 1 of scaffold mode will produce a higher-fidelity result than a raw memo.

Do’s and Don’ts

Do:

Label all inferred items as [PROPOSED] and state the reason for inference
Bundle related questions within the same category and subject in one message
Work through rounds sequentially — complete the current round before advancing
Preserve the user’s own words in scope descriptions and step text through Rounds 1-2
Update the PreSpec file in place after each round so it always reflects the confirmed state
Apply confirmed naming from Round 4 retroactively across the whole PreSpec

Don’t:

Assume inferred items are accepted — every proposal needs explicit user confirmation
Mix questions from different rounds or about unrelated subjects in a single message
Advance to a later round before the current one is complete
Rename anything before the user confirms it in Round 4
Write StarSpec documents — this agent writes docs/{name}.prespec.md only (no packages/, src/, content/, or instructions/)
Silently include unaccepted proposals in the final document

Definition of Done

All 7 clarification rounds completed or explicitly skipped by user
Open Questions section is empty or user said ‘good enough’
PreSpec file updated in place with all confirmed answers
Proposals marked as accepted, declined, or modified