| name | specification-refiner |
| description | Systematic analysis and refinement of specifications, requirements, architecture designs, and project plans. Use when the user wants to identify gaps, weaknesses, inefficiencies, or complications in a proposed plan, specification, or design document. Triggers on gap analysis, specification review, requirements analysis, architecture critique, design validation, plan assessment, weakness identification, assumption auditing, or when users share specs/plans asking for feedback. Produces actionable findings with remediations and maintains analysis state across iterations. Features sequential clarification with one question at a time, recommended answers, and immediate integration.
|
Specification Refiner
Systematically analyze and refine specifications, requirements, and architectural designs through iterative gap analysis with persistent memory, sequential clarification, and explicit user confirmation at each phase.
Core Workflow
0. ASSESS → Evaluate complexity, select mode, confirm with user
1. INGEST → Load document, confirm understanding with user
2. ANALYZE → Run SEAMS + Critical Path, build coverage map
3. CLARIFY → Sequential questions (one at a time), immediate integration
4. PRESENT → Surface detailed findings, manage remaining questions
5. ITERATE → Accept changes, re-analyze, present deltas
6. SYNTHESIZE → Present comprehensive summary for user approval
7. OUTPUT → Generate refined specification(s) in Draft status
8. VALIDATE → Review, validate traceability, advance status
Each phase ends with a full summary gate requiring user confirmation before proceeding.
Standards Integration
This skill integrates with knowledge-mcp to ground analysis in engineering standards (IEEE, ISO, INCOSE).
Auto-Query Behavior
During Phase 2 (ANALYZE), the skill automatically queries knowledge-mcp for relevant standards:
- Before SEAMS Analysis: Query "requirements engineering best practices [domain]"
- Before Critical Path: Query "dependency analysis systems engineering"
- For each finding: Query specific topics to validate against standards
Inline citations appear in findings:
"Per ISO/IEC/IEEE 12207:2017, Clause 6.4.2, requirements SHALL include verification criteria."
MCP Availability Check
Before querying, check MCP availability:
- If knowledge_search tool available: proceed with standards lookup
- If unavailable: warn user and continue without standards context
Never hallucinate citations. If MCP unavailable, state clearly:
"Note: Knowledge base unavailable. Analysis proceeds without standards context."
Graceful Degradation
If knowledge-mcp fails mid-analysis:
- Log the failure
- Continue analysis without standards
- Note in findings: "Standards citation unavailable for this finding"
Manual Commands
/lookup-standard
Query the knowledge base for specific standards information.
Syntax: /lookup-standard [natural language query]
Examples:
/lookup-standard what does ISO say about traceability/lookup-standard IEEE 15288 verification methods/lookup-standard INCOSE requirements attributes
Response Format:
## Standards Lookup: [query]
### Result 1 (87% relevant)
**Source**: ISO/IEC/IEEE 12207:2017, Clause 6.4.2, p.23
[Content excerpt]
### Result 2 (74% relevant)
**Source**: INCOSE SE Handbook, Section 4.2, pp.45-47
[Content excerpt]
---
Showing 5 of 12 results. Say "show more" for additional results.
No Results:
No direct matches found for "[query]".
Did you mean: [suggested related topics]?
Phase 0: ASSESS
On receiving a specification document, first assess complexity to determine the appropriate mode.
Complexity Assessment
Evaluate these factors:
- Document size: Page/word count
- Domains identified: Single vs. multi-domain
- Stakeholder count: How many perspectives involved
- Scope clarity: Clear, moderate, or ambiguous boundaries
Mode Selection
Present to user:
Based on initial assessment:
- Document size: [X pages / Y words]
- Domains identified: [list domains]
- Stakeholder count: [N stakeholders]
- Scope clarity: [Clear/Moderate/Ambiguous]
Recommended mode: [SIMPLE/COMPLEX]
Options:
1. Proceed with recommended mode
2. Override to SIMPLE mode
3. Override to COMPLEX mode
4. Explain the modes in more detail
Your choice:
SIMPLE Mode: Single-domain, <10 pages, clear scope
- SEAMS analysis only
- Single A-Spec output with numbered requirements (
A-REQ-NNN)
COMPLEX Mode: Multi-domain, >10 pages, ambiguous scope
- Full dual-framework analysis (SEAMS + Critical Path)
- A-Spec/B-Spec hierarchy per domain (see
references/spec-hierarchy.md)
- Requirements Traceability Matrix generation
Phase 0 Gate
Present gate summary (see references/gate-templates.md for full format). Wait for user confirmation before proceeding.
Phase 1: INGEST
Actions
- Parse document structure (sections, dependencies, interfaces)
- Create initial memory file:
analysis-state.md using template from assets/analysis-state-template.md
- Record mode selection in memory file
- Identify document type and select appropriate analysis lenses
- Note any questions that arise during parsing
Question Management
- Add questions to the Open Questions list with "Raised In: Phase 1: INGEST"
- Attempt to answer any Phase 0 questions from document content
- Update question statuses
Phase 1 Gate
Present full summary including: document info, sections identified, key entities, dependencies, and question status. See references/gate-templates.md for format. Wait for user confirmation—user may answer questions here.
Phase 2: ANALYZE
Run analysis frameworks based on mode AND build the coverage map for clarification.
Standards Integration: Before beginning analysis, check if knowledge_search tool is available. If available, automatically query relevant standards during analysis to ground findings in engineering best practices.
SIMPLE Mode
Run SEAMS Analysis only (see references/seams-framework.md).
Auto-query pattern:
- Before SEAMS: Query "requirements engineering best practices [domain]"
- For each lens finding: Query specific topics for standards validation
- Include inline citations in findings when relevant standards found
COMPLEX Mode
Run BOTH frameworks in parallel:
Framework A: SEAMS Analysis
Structure → Execution → Assumptions → Mismatches → Stakeholders
Auto-query before SEAMS: Query "requirements engineering best practices [domain]"
| Lens | Questions to Answer |
|---|
| Structure | Completeness of I/O paths? Cohesion? Coupling risks? Boundary clarity? |
| Execution | Happy path works? Edge cases covered? Failure modes handled? |
| Assumptions | Technical assumptions? Organizational? Environmental? |
| Mismatches | Requirements ↔ Design aligned? Design ↔ Implementation consistent? |
| Stakeholders | Operator view? Security view? Integrator view? End-user view? |
For each finding: Query relevant standards topic to validate and cite authoritative sources. Include inline citations in finding descriptions when standards support the observation.
Framework B: Critical Path Analysis
See references/critical-path-analysis.md for detailed methods.
Auto-query before Critical Path: Query "dependency analysis systems engineering"
- Dependency Mapping: Build N² matrix
- Critical Path Identification: Find longest/riskiest chains
- Single Points of Failure: Cascade risk components
- Bottleneck Detection: Throughput limiters
- Temporal Analysis: Sequencing issues
For each critical finding: Query standards for validation and citation.
Coverage Map Generation
CRITICAL: Build a structured coverage map using the 11-category taxonomy:
| Category | Status | Gap Count | Impact |
|---|
| Functional Scope & Behavior | [Clear/Partial/Missing] | [N] | [High/Med/Low] |
| Domain & Data Model | [Clear/Partial/Missing] | [N] | [High/Med/Low] |
| Interaction & UX Flow | [Clear/Partial/Missing] | [N] | [High/Med/Low] |
| Non-Functional Quality Attributes | [Clear/Partial/Missing] | [N] | [High/Med/Low] |
| Integration & External Dependencies | [Clear/Partial/Missing] | [N] | [High/Med/Low] |
| Edge Cases & Failure Handling | [Clear/Partial/Missing] | [N] | [High/Med/Low] |
| Constraints & Tradeoffs | [Clear/Partial/Missing] | [N] | [High/Med/Low] |
| Terminology & Consistency | [Clear/Partial/Missing] | [N] | [High/Med/Low] |
| Completion Signals | [Clear/Partial/Missing] | [N] | [High/Med/Low] |
| Assumptions & Risks | [Clear/Partial/Missing] | [N] | [High/Med/Low] |
| Misc & Placeholders | [Clear/Partial/Missing] | [N] | [High/Med/Low] |
This map drives the CLARIFY phase question prioritization.
Phase 2 Gate
Present preliminary findings summary with severity counts, coverage map summary, top 3 issues, and blocked findings. Prompt to proceed to CLARIFY phase. See references/gate-templates.md for format.
Phase 3: CLARIFY
CRITICAL: This phase uses SEQUENTIAL QUESTIONING to reduce cognitive load and enable immediate integration.
Clarification Principles
- One question at a time - Never present multiple questions
- Constrained answers - Multiple choice (2-5 options) OR short phrase (≤5 words)
- Recommended answer - Always analyze and recommend the best option
- Immediate integration - Update spec/analysis-state AFTER EACH answer
- Maximum 5 questions - Per clarification session
- Maximum 10 questions - Across entire analysis (including ITERATE loops)
Question Prioritization
Generate prioritized queue using Impact × Uncertainty scoring:
-
Score each potential question:
- Impact: How much does this affect architecture, data model, task decomposition, test design, UX, ops readiness, or compliance? (1-5)
- Uncertainty: How ambiguous is the current state? (1-5)
- Priority Score = Impact × Uncertainty
-
Apply constraints:
- Only include questions whose answers materially change implementation or validation
- Ensure category balance (don't ask 3 questions from same category)
- Exclude already-answered questions
- Exclude trivial stylistic preferences
- Favor questions that reduce downstream rework risk
-
Select top 5 by priority score
Question Format: Multiple Choice
When discrete options exist, present as:
### CLARIFY-001 [CATEGORY]
[Context: What triggered this question]
**Question**: [The specific question]
**Recommended:** Option [X] - [1-2 sentence reasoning based on best practices, risk reduction, or project context]
| Option | Description |
|--------|-------------|
| A | [Option A description] |
| B | [Option B description] |
| C | [Option C description] |
| D | [Option D description] (if needed) |
| Short | Provide a different short answer (≤5 words) |
Reply with the option letter (e.g., "A"), accept the recommendation by saying "yes" or "recommended", or provide your own short answer.
Question Format: Short Answer
When no meaningful discrete options exist:
### CLARIFY-001 [CATEGORY]
[Context: What triggered this question]
**Question**: [The specific question]
**Suggested:** [Your proposed answer] - [Brief reasoning]
Format: Short answer (≤5 words). You can accept the suggestion by saying "yes" or "suggested", or provide your own answer.
Answer Processing
- If user replies "yes", "recommended", or "suggested": Use the stated recommendation/suggestion
- If user provides option letter: Map to that option
- If user provides custom answer: Validate it fits ≤5 word constraint
- If ambiguous: Ask for quick disambiguation (doesn't count as new question)
Immediate Integration Protocol
AFTER EACH accepted answer (not at end of phase):
-
Create Clarifications section (if first answer this session):
## Clarifications
### Session YYYY-MM-DD
- Q: [question] → A: [final answer]
-
Apply to appropriate section(s):
| Answer Type | Update Location |
|---|
| Functional ambiguity | Functional Requirements section |
| User interaction/actor | User Stories or Actors subsection |
| Data shape/entities | Data Model section (fields, types, relationships) |
| Non-functional constraint | Quality Attributes section (convert vague → metric) |
| Edge case/negative flow | Edge Cases / Error Handling section |
| Terminology conflict | Normalize term across entire spec |
-
Handle conflicts:
- If clarification invalidates earlier statement, REPLACE it (don't duplicate)
- Leave no obsolete contradictory text
-
Save immediately: Atomic write after each integration
-
Update analysis-state.md: Log question as answered
Early Termination
Stop asking questions when:
- All critical ambiguities resolved (remaining questions unnecessary)
- User signals completion ("done", "good", "no more", "proceed")
- 5 questions reached in this session
- 10 total questions reached across analysis
No Questions Scenario
If no valid questions exist (full coverage), immediately report:
No critical ambiguities detected requiring formal clarification.
All categories show Clear status.
Recommend proceeding to Phase 4 (PRESENT).
Phase 3 Gate
Present clarification summary:
PHASE 3 COMPLETE: CLARIFICATION
Questions asked this session: [N]
Total questions asked (all phases): [M]
COVERAGE UPDATE:
| Category | Before | After | Notes |
|----------|--------|-------|-------|
| Functional Scope | Partial | Clear | Q1 resolved |
| Data Model | Missing | Clear | Q2, Q3 resolved |
| Edge Cases | Partial | Partial | Deferred (low impact) |
...
Clarifications integrated:
1. [Q1]: [Answer] → Updated [Section]
2. [Q2]: [Answer] → Updated [Section]
...
DEFERRED TO LATER:
- [Category]: [Reason - e.g., better suited for planning phase]
OUTSTANDING (low impact):
- [Category]: [Why not addressed - e.g., exceeds question quota]
Options:
1. Proceed to Phase 4 (PRESENT) with findings
2. Run another clarification session (if quota allows)
3. Review updated specification sections
Your choice:
Phase 4: PRESENT
Finding Format
For EACH identified issue, include: ID, title, category, severity, confidence, blocked-by status, description, evidence, impact, remediation options (with trade-offs), and related issues. See references/gate-templates.md for full template.
Presentation Order
Present findings grouped by:
- Critical blockers (must fix before proceeding)
- Significant gaps (high impact, clear remediation)
- Optimization opportunities (efficiency improvements)
- Considerations (context-dependent, need user input)
Question Management
- Present all unanswered questions explicitly
- Ask user to answer questions or confirm assumptions
- Update question tracking with answers received
Phase 4 Gate
Present findings summary with severity counts, question status, and assumptions made. Offer options: (1) Iterate, (2) Skip to Synthesize, (3) Run more clarification, (4) Review details. See references/gate-templates.md for format.
Phase 5: ITERATE
When user provides new information, constraints, or requests changes:
Actions
- Validate new input against existing analysis
- Identify affected areas in the specification
- Re-run analysis on affected sections only (delta analysis)
- Update coverage map based on new information
- Assess cascading effects on previously-identified issues
- Update memory file with new state
Triggering Additional Clarification
If iteration reveals new ambiguities:
- Check if question quota allows (10 total max)
- If yes, offer to run additional CLARIFY session
- If no, note as deferred with reason
Question Management
- Add new questions with "Raised In: Phase 5: ITERATE"
- Check if new input answers existing questions
- Update all question statuses
Phase 5 Gate
Present delta summary: changes incorporated, coverage map update, new/modified/resolved findings, key changes, question status. Offer options: (1) Continue iterating, (2) Synthesize, (3) Run clarification, (4) Review findings. See references/gate-templates.md for format.
Phase 6: SYNTHESIZE
Before generating any output, present a comprehensive summary for user approval.
Summary Contents
Present comprehensive summary covering:
- Document Overview: Title, mode, iteration count, clarification count
- Coverage Summary: Final coverage map with all categories
- Findings Resolution: By severity with resolved/unresolved breakdown, key resolutions, unresolved critical/high items
- Clarifications Applied: All Q&A with section updates
- Questions Status: Answered, unanswered (with impact), deferred (with reason)
- Assumptions: Confirmed vs. unverified
- Proposed Output Structure: Based on mode (single doc for SIMPLE, separate files for COMPLEX)
See references/gate-templates.md for full format.
Phase 6 Gate
Offer options: (1) Approve and output, (2) Return to iterate, (3) Modify structure, (4) Answer questions. Wait for explicit approval before generating output.
Phase 7: OUTPUT
Generate refined specification(s) based on mode, all in Draft status.
SIMPLE Mode Output
Generate single A-Spec document (refined-specification.md) with:
- Numbered requirements (
A-REQ-001, A-REQ-002, etc.)
- All resolved findings incorporated
- Selected remediations applied
- Clarifications section with session log
- Documented assumptions
- Remaining open questions in dedicated section
COMPLEX Mode Output
Generate specification hierarchy per domain:
A-Spec files (one per domain):
- Naming:
[domain]-a-spec.md
- Requirements:
A-REQ-[DOMAIN]-NNN
- High-level requirements defining WHAT
B-Spec files (one or more per domain):
- Naming:
[domain]-[subsystem]-b-spec.md
- Requirements:
B-REQ-[DOMAIN]-NNN
- Each requirement MUST include
Traces to: A-REQ-XXX-NNN
- Detailed requirements defining HOW
Supporting files:
traceability-matrix.md - Full RTM (see assets/traceability-matrix-template.md)clarifications-log.md - All clarification sessionscross-cutting-concerns.md (if applicable)open-items.md
See references/spec-hierarchy.md for detailed format specifications.
RTM Generation (COMPLEX mode)
- Extract all A-REQ-* from A-Spec files
- Extract all B-REQ-* from B-Spec files with their traces
- Build coverage matrix
- Calculate coverage percentage
- Identify gaps (A-Reqs with no B-Req coverage)
- Generate
traceability-matrix.md
- Update
analysis-state.md with RTM summary
Final Actions
- Set all specification statuses to Draft
- Update
analysis-state.md with completion status and RTM summary
- Present output files to user
- Summarize what was generated
- Prompt transition to Phase 8
Phase 7 Completion
Present: mode, files created with requirement counts, RTM summary (COMPLEX mode), findings addressed, clarifications integrated, assumptions documented. Prompt user to proceed to Phase 8. See references/gate-templates.md for format.
Phase 8: VALIDATE
Final review and validation phase ensuring specifications are comprehensive, traceable, and approved. Mandatory for both SIMPLE and COMPLEX modes.
Status Workflow
Specifications progress through statuses:
Draft → Reviewed → Approved → Baselined
- Draft: Initial output from Phase 7 (automatic)
- Reviewed: Technical review complete, no critical gaps
- Approved: Stakeholder sign-off received
- Baselined: Locked for change control
Validation Actions
- Completeness check: All required sections present, cross-references valid
- RTM validation (COMPLEX): Coverage percentage, gap identification
- Traceability check (COMPLEX): All B-Reqs trace to A-Reqs
- Consistency check: Terminology, formatting, priority scales aligned
- Clarification integration check: All answers properly incorporated
- Present validation findings with severity
Status Advancement
- Require explicit user approval to advance status
- Document status change with timestamp and approver
- Update
analysis-state.md with new status and history
Advancement Criteria
| Transition | Requirements |
|---|
| Draft → Reviewed | No critical RTM gaps, completeness checks pass |
| Reviewed → Approved | All high-priority issues resolved, stakeholder review |
| Approved → Baselined | Formal approval documented, change control established |
Phase 8 Gate
Present validation summary with:
- Current status and proposed advancement
- RTM coverage metrics (COMPLEX mode)
- Completeness and consistency checklist
- Clarification integration verification
- Validation findings
- Options: advance status, return to fix issues, review details
See references/gate-templates.md for full template.
Ambiguity Taxonomy (11 Categories)
1. Functional Scope & Behavior
- Core user goals & success criteria
- Explicit out-of-scope declarations
- User roles / personas differentiation
2. Domain & Data Model
- Entities, attributes, relationships
- Identity & uniqueness rules
- Lifecycle/state transitions
- Data volume / scale assumptions
3. Interaction & UX Flow
- Critical user journeys / sequences
- Error/empty/loading states
- Accessibility or localization notes
4. Non-Functional Quality Attributes
- Performance (latency, throughput targets)
- Scalability (horizontal/vertical, limits)
- Reliability & availability (uptime, recovery)
- Observability (logging, metrics, tracing)
- Security & privacy (authN/Z, data protection)
- Compliance / regulatory constraints
5. Integration & External Dependencies
- External services/APIs and failure modes
- Data import/export formats
- Protocol/versioning assumptions
6. Edge Cases & Failure Handling
- Negative scenarios
- Rate limiting / throttling
- Conflict resolution (e.g., concurrent edits)
7. Constraints & Tradeoffs
- Technical constraints (language, storage, hosting)
- Explicit tradeoffs or rejected alternatives
8. Terminology & Consistency
- Canonical glossary terms
- Avoided synonyms / deprecated terms
9. Completion Signals
- Acceptance criteria testability
- Measurable Definition of Done indicators
10. Assumptions & Risks
- Technical assumptions (infrastructure, dependencies)
- Organizational assumptions (skills, process)
- Environmental assumptions (security, compliance)
11. Misc & Placeholders
- TODO markers / unresolved decisions
- Ambiguous adjectives ("robust", "intuitive") lacking quantification
Question Tracking System
Question Categories (Expanded)
Map to the 11-category taxonomy for better coverage tracking.
Question Lifecycle
- Raised: Question identified, logged with phase and category
- Queued: Selected for clarification, prioritized by Impact × Uncertainty
- Asked: Presented to user in sequential flow
- Answered: Response received and validated
- Integrated: Applied to specification with atomic write
- Deferred: Explicitly set aside with reason and revisit trigger
Question Table Format
Track questions in analysis-state.md using tables:
Unanswered:
| ID | Question | Category | Raised In | Priority Score | Blocks |
|---|
Answered:
| ID | Question | Answer | Category | Asked In | Integrated To |
|---|
Deferred:
| ID | Question | Category | Reason | Deferred In | Revisit When |
|---|
Memory File Management
Required Memory File: analysis-state.md
Use the template from assets/analysis-state-template.md. Key sections:
- Document metadata (title, version, hash)
- Mode selection (SIMPLE/COMPLEX)
- Coverage map (11 categories)
- Analysis iterations table
- Clarification sessions log
- Active and resolved findings
- Question tracking tables (per-phase)
- Assumption register
- User-provided constraints
Update Protocol
After EACH phase AND after EACH clarification answer:
- Read current
analysis-state.md
- Update phase completion status
- Update coverage map
- Update finding statuses
- Update question tables
- Record new assumptions
- Log user decisions
- Write updated file (atomic)
Analysis Depth Calibration
Match depth to document maturity:
| Document Stage | Analysis Focus |
|---|
| Concept/Idea | Feasibility, scope clarity, key assumptions |
| Draft Spec | Completeness, internal consistency, missing sections |
| Detailed Design | Interface contracts, error handling, edge cases |
| Implementation Plan | Dependencies, sequencing, resource conflicts |
| Review/Audit | Full SEAMS sweep, stakeholder perspectives |
Quick Assessment Mode
For rapid feedback when full analysis is not needed:
- Boundaries: What's in/out of scope?
- One Thread: Trace critical path from input to output
- Three Assumptions: The riskiest unstated beliefs
- Silent Failure: What breaks without notice?
- Naive Question: What would a newcomer ask that has no answer?
Note: Quick Assessment skips the full phase gate workflow but still creates analysis-state.md.
Output Formatting
Severity Indicators
- 🔴 Critical: Blocks progress, must address
- 🟠 High: Significant risk, should address soon
- 🟡 Medium: Notable issue, plan to address
- 🟢 Low: Minor concern, address opportunistically
Confidence Qualifiers
- High confidence: Clear evidence, well-understood domain
- Medium confidence: Reasonable inference, some ambiguity
- Low confidence: Pattern recognition, needs validation
Coverage Status Indicators
- ✅ Clear: Sufficient information, no clarification needed
- ⚠️ Partial: Some gaps, may need clarification
- ❌ Missing: Critical gaps, clarification required
Handling Incomplete Information
When specifications are incomplete:
- Note the gap explicitly with category
- Score Impact × Uncertainty for prioritization
- Add to clarification queue if score warrants
- State what would be needed to complete analysis
- Offer reasonable assumptions (clearly marked)
- Add question to tracking system
- Document in assumption register
Anti-Patterns to Avoid
- Vague criticism without specific evidence
- Recommendations without trade-off analysis
- Analysis paralysis on minor issues
- Ignoring stated constraints to suggest "ideal" solutions
- Failing to update memory after iterations
- Treating all findings as equal severity
- Proceeding past a gate without user confirmation
- Losing track of open questions
- Generating output without synthesis approval
- Generating B-Specs without traces to A-Specs
- Skipping RTM generation for COMPLEX mode
- Advancing status without validation
- Baselining specs with unresolved critical gaps
- Presenting multiple questions at once during CLARIFY
- Failing to recommend an answer
- Delaying integration until end of CLARIFY phase
- Exceeding question limits (5 per session, 10 total)
