| name | clarification-loop |
| description | The S4 human-in-the-loop for /morkit:greenfield. AI generates clarifying questions per user-story/gap into clarification-log.md; BA/BrSE answers inline or marks forwarded→<stakeholder>; on re-run AI ingests answers, updates the ProjectModel OpenQuestion/FR detail, and fills <TBD> placeholders. Async + multi-session: all state lives in the markdown file so the loop resumes from the file alone. Closed Q&A renders into SRS §12. |
| category | documentation |
| keywords | ["clarification","open-questions","human-in-the-loop","greenfield","srs","resume","ba"] |
| argument-hint | --workspace morkit/output/greenfield/<proj> |
| metadata | {"author":"morkit-greenfield","version":"1.0.0"} |
Clarification Loop
Stage G4 of /morkit:greenfield. Closes the open questions raised at G3
before the bridge (G5) freezes the ProjectModel.
Conventions: ../greenfield-orchestrator/references/greenfield-conventions.md.
Template: templates/clarification-log-template.md.
Depth decision (locked: template-only)
Per the plan's deferred decision, this skill ships template-only:
- State = the markdown table. No tracker code, no deadlines/reminders engine.
- Resume by re-reading
clarification-log.md. Matches KISS/YAGNI.
- State-machine depth (deadlines, stakeholder owners, reminders) is deferred to
v2 — add it only if a real project proves template-only insufficient.
Inputs
From the run workspace morkit/output/greenfield/<proj>/:
user-story-list.md (G2), gap-analysis.md (G3) — what to question.clarification-log.md — prior rounds' state (created on round 1).- ProjectModel
open_questions[] (once the bridge has run) / any <TBD: …> markers.
Round logic
- Generate (round N): from open
<TBD> markers, G3 gaps, and existing
OpenQuestions, emit grouped questions into clarification-log.md (per US/gap).
Each Q-00x starts status: open. Do not invent answers.
- Ingest (re-run, round N+1): parse the log. For each
answered row, update
the target FR detail / fill its <TBD>, set Resolved-FR, and mark the matching
OpenQuestion.q_status = Answered. forwarded rows stay open (still waiting on a
stakeholder). Report the remaining open count for the gate.
- G4 GATE — enough-answered / force-close: via
AskUserQuestion, either close
the loop (open-count ≤ threshold, or BA forces) or run another round. Persist the
decision into state.json (stages.G4.gate).
- Closure: on close, answered Q&A flows (via the bridge) into ProjectModel
open_questions → SRS §12. Unanswered/forwarded questions carry forward as
<TBD> / Open — never silently dropped.
Resume guarantee
Because the only state is clarification-log.md, the loop survives across sessions
and days: re-invoking the skill on the same workspace continues exactly where it
left off. Use a strict table format (template columns) so answer parsing is robust.
Anti-patterns
- ❌ Inventing an answer to close a question faster → violates the no-fiction rule.
- ❌ Looping forever → the G4 gate always offers force-close.
- ❌ A second state store (DB/json) → state is the log file only (template-only depth).
