[Feature]: Document in-place clarification of assessment artifacts

[mnriem]

Problem Statement

The assess extension does not explain how users should resolve [NEEDS CLARIFICATION: …] markers before continuing. Current guidance can be read as directing users to rerun an earlier stage, even though assess is intended to be a sequential process:

intake → research → define → shape → decide

Each command normally runs once and produces an editable Markdown artifact. Completed stages are not normally rerun.

Proposed Solution

Document that users resolve clarifications by either:

1. Editing the relevant Markdown artifact directly, or
2. Asking the agent in free-form chat to incorporate the clarification.

The user may then ask the agent whether the new information resolves the blocker and to update the affected artifact accordingly.

This also applies to decision.md: users may provide missing information and ask the agent to revise the scorecard, rationale, verdict, or handoff. This is artifact refinement, not command iteration.

Update extensions/assess/README.md, its flow diagram, and speckit.assess.decide guidance to make this distinction explicit.

Alternatives Considered

Adding a dedicated speckit.assess.clarify command and clarification loop was considered. That represents a different, iterative process and is better implemented as a custom extension and preset rather than changing the core sequential assess process.

Component

Documentation

AI Agent (if applicable)

All agents

Use Cases

1. A user reviews problem.md, supplies a missing metric, and asks the agent to incorporate it before moving to shape.
2. A user receives needs-clarification in decision.md, adds the missing information, and asks the agent whether the blocker is resolved and to refine the decision artifact.
3. A team preserves a clear audit trail by updating generated artifacts rather than regenerating whole stages.

Acceptance Criteria

• The normal process remains intake → research → define → shape → decide.
• Documentation states that assess commands are sequential and normally run once.
• Documentation states that generated Markdown artifacts remain user-editable.
• Direct editing and free-form agent-assisted editing are both explained.
• Clarifications are resolved by refining existing artifacts, including decision.md when applicable.
• Evidence-related additions preserve source and confidence information.
• Guidance no longer presents rerunning completed stages as the normal clarification path.
• No dedicated clarification command or loop is introduced.

Additional Context

The distinction to document is between rerunning a stage command—which may overwrite an artifact—and refining the artifact that the completed stage produced.