refine
暂无简介
- License 许可
- MIT
- 所属仓库
- markosAMO/Alfred
- 最近更新
- 2026-10-13
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- mode
- interactive
- name
- refine
- next
- [ "research", "spec" ]
- skippable
- true
03 SKILL.md 正文
refine
Interview the user until the request is understood well enough to specify. Write nothing else: no specification, no design, no code.
This phase exists because a request arrives shorter than the thing being requested. "Add Google login" is eight words describing a week of work, and every gap left in it is filled by the model guessing.
When the orchestrator routes here
A request needs this phase when any of these hold. Otherwise the route can start past it.
- The failure behaviour is unstated. The request says what should happen when it works.
- A domain term appears that is not defined in
architecture.mdor memory. - More than one component or repository is affected.
- It requires an architectural decision that has not been made.
- There is no way to tell, from the request alone, whether the result is correct.
A request carrying none of these is already specifiable, and interviewing the user about it wastes their time.
When the request arrives as a tracker card, the same criteria apply to the card body.
The decision is proposed and confirmed, never applied silently, and the orchestrator names
the signals it matched and lets the user take the shorter answer. Those mechanics hold under
every workflow and are in skills/_shared/routing.md.
What matching them is worth, and where the shorter answer goes instead, is the running workflow's and is written in its rules file. The list above is what this phase is for; the route it argues for belongs to the workflow that declares the routes.
Materialise the inputs first
Before anything else, bring in whatever arrived as a reference: tracker cards, URLs, documents in other systems.
read each source once
write it in full to .alfred/changes/{change}/inputs/
index it under alfred/{change}/input/{slug}
Follow skills/_shared/external-inputs.md. Nothing after this phase fetches anything: the
interview, spec, design and every subagent read the materialised text.
Before asking anything
Read what is already known, and never ask for it.
inputs/ the material just materialised
architecture, conventions when the workflow hands them
recall the types the workflow declares, for prior decisions and related changes
Asking which database the project uses, when architecture.md states it, teaches the user
that answering carefully is pointless.
Open every round by naming what was assumed from these sources, so a wrong assumption is corrected instead of inherited.
The interview
Questions are asked in rounds, grouped by topic. One ask() per round carrying three or
four questions, never one question at a time.
Each round is answered before the next is asked. Later rounds depend on earlier answers: asking about integration before the scope is settled produces questions about work that turns out to be excluded.
Round 1 — Problem and scope
- What problem does this solve, and for whom?
- What does the user do today instead?
- What is explicitly out of scope?
- Is this new behaviour, or a change to behaviour that already exists?
Round 2 — Behaviour
- What happens when it works? Walk through it.
- What can go wrong, and what should happen then?
- Which edge cases matter, and which are acceptable to ignore?
- What must never happen?
The failure path is not optional. A round that produces only the happy path is not
finished, because testing-protocol.md requires both and the scenarios come from here.
Round 3 — Integration and direction
- Which parts of the system does this touch?
- Which external services are involved?
- What data is read, written or stored?
- Is there an approach you already want, or one you want ruled out?
The last question is the only one that collects a technical decision, and it collects the
user's, never the model's. An answer to it is a constraint on design, not a design.
Leave it unanswered rather than filling it in. A direction the user did not state is a
decision design should be making with the specification in front of it.
For multi-repository work, this round determines which repositories are affected and is
the input to workspace design.
Round 4 — Constraints and acceptance
- How will we know it is done?
- Are there performance, security or compliance constraints?
- Is there a deadline or a dependency on other work?
- What would make you reject this once built?
Stopping
Stop when a round produces nothing that changes the proposal. Continuing past that point
collects detail that belongs in design.
Stop early when the user says to. A partial proposal with its gaps marked is more useful than a complete one built on invented answers.
Never fill a gap by assuming. An unanswered question is written into the proposal as an
open question and carried into spec.
What it writes
## Problem
## Proposed change
## Scope
### Included
### Excluded
## Behaviour
### Happy path
### Failure paths
### Edge cases
## Integration
### Components affected
### External services
### Data
## Architectural direction
## Constraints
## Acceptance
## Open questions
## Assumptions
Architectural direction holds only what the user decided, each line with the reason they
gave. It is empty when they decided nothing, and an empty section is the normal case.
## Architectural direction
- Events, not polling. The consumer cannot be blocked by the producer.
- Reuse the existing notification service rather than adding a second one.
These are constraints design inherits, not a design. They name a direction and a reason;
they name no interface, no schema and no library.
Assumptions records what was taken from architecture.md or memory rather than asked.
spec treats those as inherited, not as decided, and a wrong one surfaces there instead of
in the code.
Completion
Follow skills/_shared/phase-protocol.md: write the artifact with its ## Handoff, update state, notify phase_completed.
The proposal is prose describing intent. It contains no SHALL, no scenarios and no delta
sections. Those belong to spec, and writing them here produces a requirement nobody
reviewed as one.