hm-l2-requirements-analysis

Files (6)

• SKILL.md
• evals.json · evals/
• rich-gate-scorecard.md · metrics/
• ears-syntax-guide.md · references/
• gap-detection-patterns.md · references/
• needs-vs-wants.md · references/

SKILL.md (first lines)

# Requirements Analysis

## Overview

Systematically diagnose existing requirements — not write them, not brainstorm them, not implement them. This skill owns gap detection, contradiction surfacing, constraint discovery, and assumption validation. It produces a structured gap report that feeds into spec-locking (`hm-spec-driven-authoring`).

**This skill answers four questions about every requirement:**
1. Is it **wrong** (contradicts another requirement or known constraint)?
2. Is it **missing** (absent scope, edge case, or constraint)?
3. Is it **vague** (unbounded terms, no measurable threshold)?
4. Is it **unvalidated** (stated as fact but actually an assumption)?

## Third-Party Source References

This skill synthesizes patterns from three inspected third-party skills:

| Source | Adopt/Adapt Decision | Local Transformation |
|---|---|---|
| `skillmd.ai/requirements-clarity` | Adopt the gap-analysis dimensions (Functional Scope, User Interaction, Technical Constraints, Business Value) and the 100-point clarity scoring rubric; adapt away from the YAGNI/KISS single-question framing. | Use Gap Type matrix with 4 diagnostic lenses. |
| `agent-skills.md/prompt-optimizer` | Adopt EARS syntax transformation rules and compound-requirement decomposition; adapt away from the prompt-optimization framing. | Use EARS as diagnostic tool — translate vague requirements INTO EARS to expose what's missing. |
| `forztf/open-skilled-sdd@openspec-proposal-creation` | Adopt the EARS SHALL/SHOULD/MAY hierarchy and scenario-format (Given/When/Then) validation; adapt away from proposal-creation workflow. | Use SHALL/SHOULD/MAY classification to detect underspecification. |

## Boundary Rules

| Nearby Workflow | Boundary |
|---|---|
| `hm-brainstorm` | Produces requirements briefs from ideation. This skill diagnoses gaps in those briefs after they exist. |
| `hm-spec-driven-authoring` | Consumes gap reports as input for spec-locking. This skill produces the gap report and hands off. |
| `hm-cross-cutting-change` | Receives constraint discovery findings when cross-cutting impacts are detected. |
| `hm-gate-orchestrator` | May route to this skill when gate validation reveals requirement insufficiency. Routes this skill's gap reports through the quality gate triad (lifecycle → spec → evidence). |
| Exploratory coding | Not enough source truth. Return blocked — "Cannot diagnose requirements without a requirements artifact to analyze." |

## Entry Gate

Proceed only when at least one of these exists:
- A PRD, spec, user story set, acceptance criteria document, or requirements brief
- An explicit user request to diagnose existing requirements
- A gate failure report from `hm-spec-driven-authoring` indicating requirement gaps

**Block if:** The user asks to "generate requirements from scratch" (route to `hm-brainstorm`) or "write a spec" (route to `hm-spec-driven-authoring`).

Before diagnosing:
1. Identify the source requirements artifact (file path, pasted document, or brief text).
2. Run `prompt-skim` if available to count requirements, detect URLs, and measure artifact size.
3. Run `prompt-analyze` if available to detect contradiction, vagueness, and missing scope signals.
4. If tools are unavailable, perform the same checks manually and note their unavailability.
5. Classify the artifact's maturity: **Incomplete** (fewer than 5 requirements or no acceptance criteria), **Draft** (5-20 requirements, partial criteria), or **Formal** (20+ requirements with structured criteria).

## The Four Diagnostic Lenses

Apply all four lenses to every requirement. Do not stop at one finding — a single requirement can be simultaneously vague AND missing its constraint chain.

### Lens 1: Gap Detection — "What's Missing?"

Four gap types to systematically identify:

| Gap Type | Detection Signal | Example |
|---|---|---|
| **Missing Scope** | Feature described but key actor, input, output, or boundary absent | "Users can export data" — what formats? from which screen? with what filters? |
| **Hidden Constraints** | Requirement assumes technical, business, or regulatory context not stated | "The system shall send notifications" — via email? push? SMS? with what latency? what retry policy? |
| **Contradictory Requirements** | Two requirements describe mutually exclusive states or behaviors | "REQ-1: Delete is permanent" + "REQ-2: Users can undo delete" — contradictory unless undo window is specified |
| **Unvalidated Assumptions** | Requirement uses undisputed language ("always", "never", "obviously") without evidence | "The database will obviously handle 10M rows" — no load profile, no index plan, no benchmark |

**Procedure:** For each requirement, create a gap entry in the diagnostic table (see template at `references/gap-detection-patterns.md`). Tag each gap with one of the four types.

For detailed detection heuristics and diagnostic templates, load `references/gap-detection-patterns.md`.

### Lens 2: EARS Precision Check — "Can This Be Made Falsifiable?"

Translate every requirement into EARS (Easy Approach to Requirements Syntax). If translation fails, the requirement is underspecified.

| EARS Pattern | Template | Use When |
|---|---|---|
| **Ubiquitous** | `The <system> SHALL <response>` | Always-true requirements without triggers |
| **Event-driven** | `WHEN <trigger>, the <system> SHALL <response>` | User actions, external events |
| **State-driven** | `WHILE <state>, the <system> SHALL <response>` | Ongoing conditions, modes |
| **Unwanted Behavior** | `IF <condition>, THEN the <system> SHALL <response>` | Error handling, edge cases, limits |
| **Optional Feature** | `WHERE <feature enabled>, the <system> SHALL <response>` | Toggle-able capabilities |
| **Complex** | `WHILE <state>, WHEN <trigger>, the <system> SHALL <response>` | Multipart conditions |

**Procedure:**
1. Take a vague requirement (e.g., "The system should be fast").
2. Attempt EARS translation: `WHEN user submits a search, the system SHALL return results` — what's missing? The "fast" threshold! You just detected a gap.
3. Record: **"Fast" is unbounded — need <N>ms at <P>th percentile for <operation>.**

For complete EARS syntax rules, keyword tables, and anti-patterns, load `references/ears-syntax-guide.md`.

### Lens 3: Constraint Discovery — "What Forces Shape This Requirement?"

Every requirement exists within constraints. Undiscovered constraints = implementation risk.

**Constraint dimensions to probe:**
- **Technical:** Platform, language, dependency, API surface, database, cache, queue
- **Operational:** Deployment model, observability, logging, monitoring, SLO/SLA
- **Security:** Auth model, data classification, encryption at rest/transit, audit trail
- **Regulatory:** GDPR, HIPAA, SOC2, PCI, data residency, retention policy
- **Performance:** Latency, throughput, concurrency, resource limits, cold start
- **Capacity:** Users, data volume, growth rate, peak load, quotas
- **Team:** Available skills, timeline, on-call rotation, bus factor
- **Cost:** Budget constraints, cloud provider lock-in, license implications

**Procedure:** For each requirement domain, ask: "What constraint would make this impossible to implement as stated?" Record missing constraints in the gap report.

### Lens 4: Needs vs. Wants — "What Does the Stakeholder Actually Need?"

Distinguish between stated asks and real needs. Use the Five Whys method:

**Procedure:**
1. Take the stated requirement: "We need a dashboard with 15 widgets."
2. Ask Why: "What decision does each widget inform?"
3. Ask Why: "What happens if that decision is delayed 1 hour? 1 day?"
4. Ask Why: "What's the cost of a wrong decision without this data?"
5. Ask Why: "Could a notification replace a widget for this use case?"
6. Classify: **Need** (missing it causes measurable harm) vs. **Want** (nice to have, no harm from absence).

For the full classification framework, the Five Whys method, and real-needs surfacing patterns, load `references/needs-vs-wants.md`.

## Main Workflow: Requirements Diagnosis

From shynlee04/hivemind-plugin, MIT.

More from shynlee04/hivemind-plugin