spec-document-elicitation
Elicit requirements from stakeholders via structured 'grill me' interviews and populate spec documents from templates. Covers the full 01_requirement phase.
- License 许可
- Unlicense
- 最近更新
- 2026-11-03
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- spec-document-elicitation
- tags
- [ "requirements", "elicitation", "product-owner", "ba", "interview", "templates", "specification", "babok" ]
- description
- Elicit requirements from stakeholders via structured 'grill me' interviews and populate spec documents from templates. Covers the full 01_requirement phase.
02 资源文件 1
- 参考文档references/template-field-guide.md4.4 KB
03 SKILL.md 正文
Spec Document Elicitation
Elicit requirements from a stakeholder (the user) through structured Q&A and populate standardized specification documents from templates. The "grill me" pattern: sequential clarify() calls with curated multiple-choice options, each answer feeding the next question and the document being written.
Trigger Conditions
Load this skill when:
- A user asks to "grill me," "interview me," or "ask me questions" to set up project specifications
- A user references the
project_specrepository (F:\projects\project_spec) and wants foundation documents populated - A user wants Business Objectives, User Stories, Acceptance Criteria, or Stakeholder Analysis written from scratch
- A user says "I'm ready, ask me" in the context of a new project/spec
Repository Structure
F:\projects\project_spec\
├── README.md # Platform overview & service catalog
├── template\ # Blank templates (the source of truth)
│ └── 01_requirement\
│ ├── 011_business_objective.md # SMART goals, KPIs, risk matrix
│ ├── 012_user_stories.md # As-a-I-want-so-that, epics, story maps
│ ├── 013_acceptance_criteria.md # Given-When-Then BDD format
│ ├── 014_stakeholder_analysis.md # Influence/interest matrix
│ └── 015_definition_of_done.md # DoD criteria
│ └── 02_design\ ... 07_pm\ # Later phases
└── spec\ # Populated specs (one dir per project)
└── <project_name>\
└── 01_requirement\ # Where documents get written
Reference example: spec/tiny_mchwa/ — a completed spec to study for format and depth.
Elicitation Workflow
Phase 1: Discovery (read, don't ask)
- Read
F:\projects\project_spec\README.md— understand the project context - Read all relevant templates from
F:\projects\project_spec\template\01_requirement\ - Read an existing completed spec (e.g.,
spec/tiny_mchwa/) as a reference - Scan the project's spec directory to see what already exists
Phase 1.5: Structure Decision (multi-service projects only)
When the project has multiple discrete services (e.g., a platform with foundation services + business microservices), ask the structure question BEFORE writing any document beyond the platform-level Business Objectives:
"Should each service get its own deep-dive documents, with the platform serving as an umbrella? Or should all stories live in one monolithic platform doc?"
The recommended pattern (and the one to lead with):
spec/
├── <platform>/ ← UMBRELLA: platform-level docs only
│ ├── README.md ← Architecture overview, service map, quick links
│ └── 01_requirement/
│ ├── 011_business_objective.md ← Cross-cutting objectives (all services)
│ ├── 012_user_stories.md ← Consolidated story map + links to service docs
│ └── 014_stakeholder_analysis.md ← All personas (human + AI)
│
├── <service-a>/ ← DEEP DIVE: self-contained, AI-persona-ready
│ └── 01_requirement/
│ ├── 011_business_objective.md ← Service-specific objectives (subset of platform)
│ ├── 012_user_stories.md ← That service's stories only
│ └── 013_acceptance_criteria.md ← BDD criteria for that service's stories
│
├── <service-b>/ ← Same structure, fully independent
│ └── 01_requirement/
│ └── ...
Why this pattern:
- Each service spec is self-contained — an AI persona can pick up one directory and build without reading the whole platform
- The platform umbrella provides cross-service traceability (story → objective, service → dependency) without duplicating content
- Story points, epics, and milestones are consolidated at the platform level; details live in service docs
012_user_stories.mdat the platform level is a thin umbrella — story map + cross-service dependencies + links. Not a copy of service-level stories.
When NOT to split:
- Single-service projects (e.g., one microservice with no platform layer)
- The platform document is the only document needed (no deep dives)
- Tiny projects where splitting adds more overhead than value
Phase 2: Grilling (structured Q&A)
Use clarify() with multiple-choice options. Sequencing matters — start broad, then narrow:
Round 1 — The Big Picture:
- Primary motivation (why build this?)
- Users and scale (self only, friends, public-ready)
- Timeline and delivery preferences (docs first? code first?)
Round 2 — Scope & Architecture:
- MVP scope (what's the minimum viable set?)
- Technology preferences or constraints
- Deployment environment (Docker Compose, Kubernetes, bare metal)
Round 3 — Drilling into specifics:
- For each component/service in scope, ask targeted questions
- Use prior answers to constrain subsequent choices
- Each answer should narrow options for the next question
Rules for grill questions:
- ALWAYS provide 3-4 curated choices via
clarify(choices=[...])— never open-ended unless no good options exist - Design choices that progressively narrow scope
- Each choice must force a real decision between distinct paths
- After 4-5 rounds of questions, you should have enough to write a document
- If the user picks "Other," honor it and adapt
Phase 3: Document Population
For each document, follow the template structure precisely:
- Copy the template's frontmatter — replace placeholders with real values
- Fill every section — empty sections with placeholder text are unacceptable
- Use real data from the interview — never fabricate metrics, names, or numbers
- Mark unknowns honestly — use "TBD" rather than guessing
- Trace stories to objectives — each user story must map to a business objective
- Include "Related Documents" cross-references at the bottom
Document Order (dependencies)
For the platform umbrella:
011_business_objective.md— defines the WHY (objectives, KPIs, success criteria) for all services012_user_stories.md— consolidated story map + inter-service traceability + links (thin umbrella, NOT a copy)014_stakeholder_analysis.md— defines WHO CARES (influence, concerns, engagement)
For each service deep-dive:
011_business_objective.md— service-specific objectives (subset of platform objectives)012_user_stories.md— that service's stories only, self-contained for an AI persona013_acceptance_criteria.md— BDD criteria for that service's stories (Given-When-Then)
Rule: The platform umbrella's 012_user_stories.md links to service-level story docs. It does NOT duplicate them. Each service doc is the source of truth for its own stories.
Phase 4: Present & Continue
After each document:
- Summarize what was written (2-3 lines)
- Show key metrics (e.g., "5 objectives," "18 stories across 4 epics")
- Ask "Review or continue?" — don't assume all documents in one session
Diagram Preferences
- Architecture / data flow diagrams:
flowchart TBorflowchart LRwithsubgraphblocks, solid arrows (-->) for data flow, dashed (-.->) for cross-cutting concerns (auth validation, metrics scraping, service registration). Color-code nodes by layer (edge, foundation, gateway, observability, business). - Project / directory structure:
treeView-betawith├──/└──tree lines and→annotations for descriptions. NEVER usemindmapfor project structure — the user explicitly corrected this. NEVER use ASCII art boxes. - Dependency graphs:
flowchartwith color-coded priority nodes (🔴 red fill for must-have, 🟡 orange for should-have, 🟢 green for nice-to-have). - Stakeholder maps:
quadrantChartwith labeled quadrants. - Execution order / sprint plans:
flowchart LRwith colored initiative nodes and dependency arrows. - Always wrap Mermaid in ```mermaid fences. Mermaid renders natively in Obsidian and GitHub.
Design Review Feedback Loop
Requirements documents are NOT static. After PO writes
01_requirement, the Design/Dev persona reviews them against real architecture constraints and produces a meeting minute (placed inspec/meeting-minute/) listing decisions and affected documents. The PO must then update ALL affected docs and produce a response meeting minute confirming the changes.
The feedback loop pattern:
PO writes 01_requirement docs
→ Design/Dev persona reviews against real infra
→ Design/Dev produces meeting minute (affect-doc.md) with:
- Decisions made (D1, D2, ... Dn)
- Documents requiring changes (severity: 🔴 Critical / 🟡 Moderate)
- Specific line-level changes needed
→ PO reads the meeting minute
→ PO grills user on any unclear decisions
→ PO updates ALL listed documents (bump version to 0.2)
→ PO writes a response meeting minute confirming:
- What changed in each document
- Updated story/point/AC counts
- Architecture rules (the new ground truth)
→ PO hands back to Design persona
Key rules for the feedback loop:
- Read the meeting minute completely before touching any document. Understand the full scope of changes.
- Grill the user on ambiguous decisions — some design decisions need PO clarification (e.g., "does Gate see auth traffic at all?" or "is Valkey for rate limiting or something else?").
- Update docs in order of severity — 🔴 Critical docs first (they block development).
- Don't forget the README — both platform-level and root-level READMEs need updating when architecture changes. This is easy to miss.
- Bump document versions — changed docs go from
0.1→0.2with a revision history entry. - Produce a response meeting minute — this is the contract that tells the next persona what changed and that requirements are now aligned.
Post-Requirements Deliverables
After 01_requirement is complete and services are being built/deployed, the PO persona also produces:
Phase Plans (plan/ directory)
When the DevOps/Dev persona proposes a new phase (e.g., "Phase 2: add CI/CD, observability, alerting"), the PO:
- Reads the DevOps proposal meeting minute
- Grills the user on decisions (scope, notification channel, deploy strategy, retention policy)
- Writes a structured Phase Plan with: initiatives, PO decisions, execution order (Mermaid), action items, Definition of Done, and transition criteria
Construction Overview (03_construction/031_README_developer_guide.md)
A platform-level document that ties together each service's 03_construction/ folder. Contains:
- Service inventory (treeView-beta diagrams)
- Monorepo structure
- Development workflow (local dev + CI/CD deploy flow)
- Build profiles per tech stack
- Shared resources table
- Coding standards summary
Meeting Minutes (spec/meeting-minute/)
Every cross-persona handoff produces a meeting minute. These are the contracts between personas:
- Format: YAML frontmatter + structured sections (decisions, documents affected, action items)
- Named:
<topic>_<date>.md(e.g.,po-update-2026-07-22.md) - Include severity tags (🔴/🟡) on affected documents
- Include a handoff checklist at the end
Pitfalls
- DON'T write all documents before the user has seen any. Write one, present it, get implicit or explicit go-ahead, then write the next.
- DON'T ask the same question twice. Track what's been answered. Each round builds on prior answers.
- DON'T use open-ended
clarify()when you can provide choices. The user chose "grill me" mode — they want to pick from options. - DON'T fill template fields with placeholder text. If you lack data, ask another question or mark it
TBD. - DON'T skip sections assuming they're irrelevant for a small project. A portfolio project needs full documents. Every section signals rigor.
- When the user changes a fundamental assumption mid-session (e.g., "Guard IS the Keycloak instance itself"), note that earlier documents may need updating. Flag it explicitly.
- DON'T write monolithic
012_user_stories.mdwith all services' stories in one file for multi-service platforms. This forces every persona to read everything. Ask the structure question (Phase 1.5) BEFORE populating story documents. If the user wants service-level docs, split the stories and make the platform012a thin umbrella. - DON'T restructure mid-session without asking. If the user suggests a structural change, pause and confirm the pattern before applying it everywhere. "Are all three foundation services getting independent docs? What about business services?"
- DON'T forget the READMEs when architecture changes. When applying design review changes, both the platform-level README (
spec/<platform>/README.md) AND the root-level README (project_spec/README.md) must be updated with new architecture diagrams, service statuses, ports, domains, and phase tracking. These are high-visibility documents — stale information here undermines trust in the rest of the spec. - DON'T replace entire table rows when adding rows. Use targeted
patchoperations with enough context to be unique. Replacing a row's content when you meant to insert a new row silently deletes data.
04 同仓库更多 Skills
project-spec-docs
Fill/update project_spec docs (templates, MM handoffs).
penpot-mcp
Penpot MCP: connect, verify, and fix streaming via nginx.
nginx-streaming-proxy
Configure nginx for streaming endpoints (SSE, MCP, WS).
branding-ci
Use for brand/CI identity, style guides, and brand docs.
yuanbao
Yuanbao (元宝) groups: @mention users, query info/members.
slidev
Create and present web-based slidedecks for developers using Slidev with Markdown, Vue components, code highlighting, animations, and interactive features. Use when building technical presentations, conference talks, code walkthroughs, teaching materials, or developer decks.