Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion bundles/assess/bundle.yml
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ requires:
provides:
extensions:
- id: "assess"
version: "1.0.2"
version: "1.0.3"
workflows:
- id: "assess"
version: "1.0.0"
Expand Down
15 changes: 8 additions & 7 deletions docs/guides/assessment.md
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,7 @@ The agent records the scorecard, rationale, and verdict in `decision.md`.
| Verdict | What it means | What to do |
| --- | --- | --- |
| `go` | The problem and evidence are adequate and a concept is recommended | Decide whether to act; optionally hand a software idea to SDD |
| `needs-clarification` | Specific unknowns still block a defensible decision | Refine the affected artifacts with the missing information |
| `needs-clarification` | Specific unknowns still block a defensible decision | Refine the affected artifacts, then re-run `/speckit-assess-decide` |
| `kill` | The idea is not worth pursuing now | Keep the recorded rationale; stopping is a successful outcome |

All five artifacts live under `.specify/assessments/offline-mode/`. None of the
Expand All @@ -90,14 +90,15 @@ The usual flow runs each command once. When an artifact contains
in free-form chat to incorporate the missing information:

```text
Update .specify/assessments/offline-mode/problem.md with these confirmed success metrics: <your metrics>. Update any dependent wording and revise decision.md if this resolves the blocker. Preserve source and confidence tags.
Update .specify/assessments/offline-mode/problem.md with these confirmed success metrics: <your metrics>. Update any dependent wording. Preserve source and confidence tags.
```

Do not automatically regenerate the entire stage. Ask the agent to review
whether the new facts clear the blocker and revise the downstream scorecard,
verdict, or handoff accordingly. Rerunning a command is an exception, such as
replacing a discarded draft, and existing artifacts must not be overwritten
without confirmation.
Do not automatically regenerate the entire stage. Once the refined artifacts
answer the blocking questions, request reassessment by re-running
`/speckit-assess-decide`: it rebuilds the scorecard, verdict, and handoff from
the updated artifacts, and asks before overwriting the existing `decision.md`.
Comment on lines +98 to +99
Rerunning an earlier command is an exception, such as replacing a discarded
draft, and existing artifacts must not be overwritten without confirmation.

## Optional handoff to SDD

Expand Down
17 changes: 11 additions & 6 deletions docs/reference/agentic-assessment.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,8 @@ directory exists.

Existing artifacts are not overwritten without confirmation. In automated mode,
commands refuse to overwrite them. For routine clarification, refine the existing
artifact rather than rerunning the command.
artifact rather than rerunning its command; the verdict is then updated by
re-running `decide`, which asks before overwriting the previous `decision.md`.

## Decisions and evidence

Expand All @@ -82,11 +83,15 @@ A documented decision to stop is a useful result.
Run each stage once in the usual flow. To resolve clarification markers or a
`needs-clarification` verdict, edit the affected Markdown directly or ask the
agent in free-form chat to incorporate the missing facts. Preserve sources and
confidence tags, then review dependent artifacts and revise `decision.md` as
needed. This is artifact refinement, not repeated command execution.

Rerunning an earlier command is reserved for exceptions such as a wrong slug or
discarded draft. See the
confidence tags, and review dependent wording across the affected artifacts —
a clarification in one artifact can leave a downstream artifact stale.
`decision.md` itself is not revised in place: once the refined artifacts answer
the blocking questions, request reassessment by re-running the decide command,
which rebuilds the scorecard, verdict, and handoff from the updated artifacts
and asks before overwriting the previous decision.

Rerunning a command earlier than decide is reserved for exceptions such as a
wrong slug or discarded draft. See the
[guided clarification example](../guides/assessment.md#resolve-unknowns-by-refining-the-artifacts).

## Handoff and guardrails
Expand Down
8 changes: 4 additions & 4 deletions extensions/assess/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,8 +26,8 @@ flowchart LR
A[intake] --> R[research] --> D[define] --> S[shape] --> C{decide}
C -->|go| SPEC[/"/speckit-specify"/]
C -->|kill| X[closed, recorded]
C -.->|needs-clarification| F[refine named artifact in place]
F -.->|then revise decision.md| C
C -.->|needs-clarification| F[user refines named artifact in place]
F -.->|then re-run decide| C
Comment thread
Copilot marked this conversation as resolved.
Resolved
```

## Commands
Expand Down Expand Up @@ -65,11 +65,11 @@ Resolve them by refining the existing file:
1. **Edit the Markdown directly** (fill in the missing metric, owner, constraint, and so on), or
2. **Ask the agent in free-form chat** to incorporate the missing information into that artifact.

Then ask whether the new information clears the blocker and to update any downstream wording that depended on it. That includes `decision.md`: you can supply the missing facts and ask the agent to revise the scorecard, rationale, verdict, or handoff. That is artifact refinement, not command iteration.
Then ask whether the new information clears the blocker and to review and update dependent wording across the affected artifacts — a clarification in `problem.md` can leave downstream `concept.md` wording stale, and `decide` reads both. `decision.md` is the exception — it is rebuilt by the command, not edited in place: once the refined artifacts answer the blocking questions, request reassessment by re-running `/speckit-assess-decide`. It rebuilds the scorecard, rationale, verdict, and handoff from the updated artifacts, and asks before overwriting the previous decision.

When you add evidence, keep the source and confidence tags the research stage already uses (`ASSUMPTION` vs cited claims). Do not invent citations.

Rerunning an earlier assessment command is the exception (for example after a wrong slug or a discarded draft), not the default path for answering clarification markers.
Rerunning an assessment command earlier than `decide` is the exception (for example after a wrong slug or a discarded draft), not the default path for answering clarification markers.

## Slug Conventions

Expand Down
4 changes: 2 additions & 2 deletions extensions/assess/commands/speckit.assess.decide.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ description: "Apply a go / needs-clarification / kill gate and hand survivors of

# Decide: Go, Clarify, or Kill

Render the **verdict** on an assessed idea and record it at `.specify/assessments/<slug>/decision.md`. This is the gate between discovery and delivery: a **go** hands the idea off to `__SPECKIT_COMMAND_SPECIFY__`; a **kill** stops it with a documented reason; **needs-clarification** sends it back to an earlier stage. Killing ideas here is a success, not a failure — that is the entire point of an assessment pipeline.
Render the **verdict** on an assessed idea and record it at `.specify/assessments/<slug>/decision.md`. This is the gate between discovery and delivery: a **go** hands the idea off to `__SPECKIT_COMMAND_SPECIFY__`; a **kill** stops it with a documented reason; **needs-clarification** reports the blocking unknowns and waits for the user to refine the artifacts and re-run `decide`. Killing ideas here is a success, not a failure — that is the entire point of an assessment pipeline.

Decide **judges; it does not spec or build.** It weighs the evidence already gathered and commits to a defensible call.

Expand Down Expand Up @@ -85,7 +85,7 @@ Write `ASSESS_DIR/decision.md`:
- The path `.specify/assessments/<ASSESS_SLUG>/decision.md`.
- The next step, by verdict:
- **go** → `__SPECKIT_COMMAND_SPECIFY__` using the handoff summary as its input.
- **needs-clarification** → re-run the named stage (e.g. `__SPECKIT_COMMAND_ASSESS_RESEARCH__ slug=<ASSESS_SLUG>`).
- **needs-clarification** → report the blocking questions and stop — do not resolve them here. The user supplies the missing information by refining the named artifact in place (editing the Markdown directly, or explicitly directing an agent), then requests reassessment by re-running `__SPECKIT_COMMAND_ASSESS_DECIDE__ slug=<ASSESS_SLUG>`, which consumes the updated artifacts. Re-run an earlier stage (e.g. `__SPECKIT_COMMAND_ASSESS_RESEARCH__ slug=<ASSESS_SLUG>`) only when the answer changes that stage's inputs.
Comment thread
Copilot marked this conversation as resolved.
Resolved
- **kill** → none; the assessment is closed. The record remains for future reference.

## Guardrails
Expand Down
2 changes: 1 addition & 1 deletion extensions/assess/extension.yml
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ schema_version: "1.0"
extension:
id: assess
name: "Idea Assessment Pipeline"
version: "1.0.2"
version: "1.0.3"
description: "Assess an idea before Spec-Driven Development via intake, research, define, shape, and decide. A go verdict hands off to /speckit.specify; a kill closes it. Lives under .specify/assessments/<slug>/"
category: "process"
effect: "read-write"
Expand Down
2 changes: 1 addition & 1 deletion extensions/catalog.json
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@
"assess": {
"name": "Idea Assessment Pipeline",
"id": "assess",
"version": "1.0.2",
"version": "1.0.3",
"description": "Assess an idea before Spec-Driven Development via intake, research, define, shape, and decide. A go verdict hands off to /speckit.specify; a kill closes it. Lives under .specify/assessments/<slug>/",
"author": "spec-kit-core",
"repository": "https://github.com/github/spec-kit",
Expand Down
46 changes: 46 additions & 0 deletions tests/extensions/assess/test_assess_extension.py
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,52 @@ def test_command_files_exist(self):
cmd = EXT_DIR / "commands" / f"{name}.md"
assert cmd.is_file(), f"Missing command file: {cmd}"

def test_decide_needs_clarification_step_reports_and_stops(self):
"""The decide report-back must keep refinement and reassessment apart
(#5325, maintainer direction on PR #5329).

A needs-clarification verdict means decide reports the blocking
questions and stops. The *user* supplies the missing information by
refining the named artifact in place (editing the Markdown directly,
or explicitly directing an agent), and reassessment then goes through
re-running the decide command against the updated artifacts -- never
through the agent revising decision.md on its own. The command used to
say the unconditional next step was "re-run the named stage" (skipping
refinement); an interim wording swung the other way and told the agent
to "revise decision.md" in place (skipping the command). Pin the
middle: refinement is in place and user-driven, reassessment is an
explicit decide re-run, and re-running an *earlier* stage stays the
guarded exception.
"""
text = (EXT_DIR / "commands" / "speckit.assess.decide.md").read_text(
encoding="utf-8"
)
# The report-back next step is the arrow line; the verdict definition
# and the decision.md output template also mention the verdict and are
# deliberately untouched (#4402 kept the output template).
step = next(
line
for line in text.splitlines()
if line.lstrip().startswith("- **needs-clarification** →")
)
# The opening summary must not contradict the report-back step by
# sending the idea back to an earlier stage unconditionally.
assert "sends it back to an earlier stage" not in text
# decide reports and stops; it does not resolve the unknowns itself.
assert "report the blocking questions and stop" in step
# Refinement happens in the artifact, driven by the user.
assert "refining the named artifact in place" in step
# Reassessment goes through the command, not in-place decision edits.
assert "__SPECKIT_COMMAND_ASSESS_DECIDE__" in step
assert "revise `decision.md`" not in step
assert "re-run the named stage" not in step
# An earlier-stage re-run may be offered only as the guarded
# exception, after the decide re-run, never as the default next step.
decide_rerun = step.find("__SPECKIT_COMMAND_ASSESS_DECIDE__")
earlier = step.find("Re-run an earlier stage")
assert earlier != -1 and earlier > decide_rerun
assert "only when" in step[earlier:]


# ── Catalog registration ─────────────────────────────────────────────────────

Expand Down