specification-refiner

What this skill does

# 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
**S**tructure → **E**xecution → **A**ssumptions → **M**ismatches → **S**takeholders

**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 Signal