specification-refiner

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:

1. Before SEAMS Analysis: Query "requirements engineering best practices [domain]"
2. Before Critical Path: Query "dependency analysis systems engineering"
3. 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:

1. Log the failure
2. Continue analysis without standards
3. 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

1. Parse document structure (sections, dependencies, interfaces)
2. Create initial memory file: analysis-state.md using template from assets/analysis-state-template.md
3. Record mode selection in memory file
4. Identify document type and select appropriate analysis lenses
5. 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:

1. Before SEAMS: Query "requirements engineering best practices [domain]"
2. For each lens finding: Query specific topics for standards validation
3. 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"

1. Dependency Mapping: Build N² matrix
2. Critical Path Identification: Find longest/riskiest chains
3. Single Points of Failure: Cascade risk components
4. Bottleneck Detection: Throughput limiters
5. 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

1. One question at a time - Never present multiple questions
2. Constrained answers - Multiple choice (2-5 options) OR short phrase (≤5 words)
3. Recommended answer - Always analyze and recommend the best option
4. Immediate integration - Update spec/analysis-state AFTER EACH answer
5. Maximum 5 questions - Per clarification session
6. Maximum 10 questions - Across entire analysis (including ITERATE loops)

Question Prioritization

Generate prioritized queue using Impact × Uncertainty scoring:

1. 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

2. 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

3. 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**: 

---

*Content truncated.*