Specification Refiner Skill

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 sessions
cross-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)

Agent Skills: Specification Refiner

Install this agent skill to your local

Skill Files