gap-analysis

name	gap-analysis
description	This skill should be used when analyzing design documents, specifications, or plans for completeness gaps, architectural issues, security concerns, and performance implications. Provides focus-specific detection patterns for the designer agent.
user-invocable	false
allowed-tools	Read, Grep, Glob

Gap Analysis

Domain expertise for detecting gaps in design documents, specifications, and plans before implementation begins.

Iron Law

GAPS IN DESIGN BECOME BUGS IN PRODUCTION

Every undefined error state, vague requirement, and missing integration point is a bug waiting to be written. Catch gaps in the plan so the implementation reflects reality, not assumption. Evidence-required: every gap must cite specific text from the artifact.

---

Focus Areas

1. Completeness

Detect missing pieces that will block or break implementation.

Detection patterns:

• Missing acceptance criteria — requirements without testable success conditions
• Undefined error states — happy path described, failure paths absent
• Vague requirements — "fast", "secure", "user-friendly" without measurable thresholds
• Ambiguous user journeys — "user submits form" without specifying what happens next
• Missing rollback specification — no recovery path if operation partially fails
• Unspecified data constraints — fields mentioned without type, size, or validation rules

Evidence trigger: Any requirement phrase that cannot be directly translated into a test case.

2. Architecture

Detect design decisions that conflict with existing patterns or create structural problems.

Detection patterns:

• Implied patterns violating existing conventions — new module structure that contradicts codebase layout
• Missing integration points — feature touches shared state but integration method unspecified
• Layering issues — business logic pushed to wrong layer (e.g., validation in presentation layer)
• Undeclared dependencies — feature needs data/service not mentioned in scope
• Missing schema changes — new data structure implied but migration not mentioned
• Shared resource contention — multiple features/requests accessing same resource without concurrency plan

Evidence trigger: Any design element that references an existing system component without specifying the integration contract.

3. Security

Detect authentication, authorization, and data protection gaps.

Detection patterns:

• Auth gaps — feature creates new endpoints or data access without specifying auth requirements
• Input validation missing — user-provided data consumed without specifying sanitization
• Secret handling — credentials, tokens, or keys mentioned without specifying storage/transmission
• OWASP implications — mass assignment, IDOR, SSRF risks implied by the design
• Privilege escalation paths — role or permission changes without specifying boundary checks
• Audit trail missing — sensitive operations without logging or change tracking

Evidence trigger: Any data flow that crosses a trust boundary without specifying the security control.

4. Performance

Detect design decisions that will cause performance problems at scale.

Detection patterns:

• N+1 patterns implied — loop-based data fetching without batch operation specified
• Missing caching strategy — repeated expensive operations (DB queries, API calls) without cache layer
• Concurrency concerns — shared mutable state accessed without locking or isolation strategy
• Query patterns — filtering/sorting on unindexed fields implied by the feature
• Unbounded result sets — list operations without pagination or size limits
• Synchronous blocking — long-running operations blocking request threads without async design

Evidence trigger: Any data access pattern that scales linearly with user count or data volume without a mitigation strategy.

5. Consistency (multi-issue only)

Detect contradictions and duplications across multiple issue specifications.

Detection patterns:

• Cross-issue contradictions — Issue A says feature X works one way, Issue B implies another
• Duplicate requirements — same functionality specified in multiple issues without coordination
• Conflicting scope — one issue's in-scope is another issue's out-of-scope
• Naming conflicts — same entity called different names across issues
• Interface mismatches — Issue A produces output that Issue B consumes, but shapes differ

Evidence trigger: Any requirement in one issue that cannot coexist with a requirement in another issue.

6. Dependencies (multi-issue only)

Detect ordering constraints and shared resource conflicts across issues.

Detection patterns:

• Inter-issue ordering — Issue B depends on data/schema/interface created by Issue A
• Shared resources — multiple issues modify the same file, table, or API without coordination
• Breaking change propagation — one issue changes a contract that other issues assume stable
• Circular dependencies — two issues each require the other to be implemented first
• Implicit sequencing — implementation order not specified but technically required

Evidence trigger: Any issue that references state, contracts, or resources that may be in flux due to another issue in the batch.

7. Compliance (when devflow-compliance installed)

Detect regulatory gaps that security doesn't cover. Load devflow:compliance references before analyzing.

Detection patterns:

• Missing audit trails on regulated mutations — writes to financial records, PHI, PCI-scoped data without durable logging
• PII flows without retention/erasure specification — data collected but deletion/expiry policy absent
• Missing encryption requirements — regulated data at rest or in transit without specified encryption control
• Sensitive data in observability — PII or credentials leaking into logs, traces, or metrics
• IaC exposure — infrastructure definitions without required security controls (open ports, unencrypted storage, missing IAM boundaries)
• Self-approval flows — change requires segregation of duties (SOX/SOC 2 CC8.1) but single-actor path exists in the design

Explicit scope note: Do NOT duplicate §3 Security's checks (secrets, injection, authZ). Compliance focus is on regulatory control requirements — retention periods, erasure rights, audit completeness, and segregation of duties — not general application security.

Evidence trigger: Any regulated-data flow or infrastructure element in the design that does not specify a required control (retention policy, encryption spec, audit log destination, approval workflow).

---

Extended References

Reference	Content
references/check-layers.md	Detailed detection checklists per focus area

Severity Guidelines

Level	Criteria	Examples
CRITICAL	Gap that will cause data loss, security breach, or system failure	Missing auth on sensitive endpoint, undefined error recovery for financial transaction
HIGH	Gap that will cause incorrect behavior or significant technical debt	Missing pagination on unbounded list, undefined race condition in concurrent update
MEDIUM	Gap that will require rework if unaddressed	Vague acceptance criteria, missing caching strategy for frequently-read data
LOW	Gap that is an improvement opportunity	Naming inconsistency, minor UX ambiguity with obvious resolution

Confidence Calibration

• Report at 80%+: Gap is clearly present, evidence directly cited
• Suggest at 60-79%: Plausible gap, depends on context not visible in artifact
• Drop below 60%: Speculation without textual evidence

Output format per gap:

**[FOCUS] Gap: {title}** — Severity: {CRITICAL/HIGH/MEDIUM/LOW} | Confidence: {n}%
Evidence: "{quoted text from artifact}"
Issue: {what is missing or contradictory}
Resolution: {concrete action to address the gap}