Analyze a specification before implementation to assess backward compatibility impact, identify risks, find gaps, and produce a readiness report. Use when the user says "analyze spec", "pre-implement", "check spec impact", "spec readiness", "BC analysis", "backward compatibility check", "what can go wrong", or "spec gap analysis". Produces an actionable report with BC violations, missing sections, risk assessment, and suggested spec improvements.
Performs a thorough pre-implementation analysis of a specification to catch issues before any code is written. Produces a structured report covering backward compatibility, spec completeness, risk assessment, AGENTS.md compliance, and a remediation plan.
.ai/specs/ or .ai/specs/enterprise/.BACKWARD_COMPATIBILITY.md — the 13 contract surface categories..ai/lessons.md for known pitfalls.AGENTS.md, identify all relevant AGENTS.md guides for affected modules/packages..ai/skills/code-review/references/review-checklist.md.For each phase/step in the spec, check against ALL 13 contract surface categories:
| # | Surface | Check |
|---|---|---|
| 1 | Auto-discovery file conventions | Does the spec rename/remove any convention files or exports? |
| 2 | Type definitions & interfaces | Does the spec remove/narrow required fields on public types? |
| 3 | Function signatures | Does the spec change required params or return types? |
| 4 | Import paths | Does the spec move modules without re-export bridges? |
| 5 | Event IDs | Does the spec rename/remove event IDs or payload fields? |
| 6 | Widget injection spot IDs | Does the spec rename/remove spot IDs? |
| 7 | API route URLs | Does the spec rename/remove API endpoints or response fields? |
| 8 | Database schema | Does the spec rename/remove columns or tables? |
| 9 | DI service names | Does the spec rename registration keys? |
| 10 | ACL feature IDs | Does the spec rename feature IDs (stored in DB)? |
| 11 | Notification type IDs | Does the spec rename notification type strings? |
| 12 | CLI commands | Does the spec rename/remove CLI commands? |
| 13 | Generated file contracts | Does the spec change generated export names or BootstrapData? |
For each violation found:
Verify the spec includes all required sections (per spec-writing skill):
For each missing section, note what should be added and why.
Check that the spec's proposed implementation follows all relevant AGENTS.md rules:
Module structure:
packages/core/, packages/ui/, apps/mercato/src/modules/)setup.ts declare defaultRoleFeatures for new features in acl.ts?Data & security:
findWithDecryption for entity queries?Events & side effects:
createModuleEvents()?UI conventions:
CrudForm/DataTable for CRUD UI?Commands:
extractUndoPayload() referenced?Identify risks in these categories:
Technical risks:
Integration risks:
Dependency risks:
For each risk, assign: High / Medium / Low severity and a mitigation strategy.
Identify what's missing from the spec that would be needed for implementation:
Produce a structured report in this format:
# Pre-Implementation Analysis: {Spec Title}
## Executive Summary
{2-3 sentences: overall readiness, critical blockers, recommendation}
## Backward Compatibility
### Violations Found
| # | Surface | Issue | Severity | Proposed Fix |
|---|---------|-------|----------|-------------|
| 1 | {category} | {description} | Critical/Warning | {migration path} |
### Missing BC Section
{Note if spec lacks "Migration & Backward Compatibility" section}
## Spec Completeness
### Missing Sections
| Section | Impact | Recommendation |
|---------|--------|---------------|
| {section} | {what breaks without it} | {what to add} |
### Incomplete Sections
| Section | Gap | Recommendation |
|---------|-----|---------------|
| {section} | {what's missing} | {what to add} |
## AGENTS.md Compliance
### Violations
| Rule | Location | Fix |
|------|----------|-----|
| {rule from AGENTS.md} | {spec section/step} | {how to fix} |
## Risk Assessment
### High Risks
| Risk | Impact | Mitigation |
|------|--------|-----------|
| {risk} | {impact} | {mitigation} |
### Medium Risks
| Risk | Impact | Mitigation |
|------|--------|-----------|
### Low Risks
| Risk | Impact | Mitigation |
|------|--------|-----------|
## Gap Analysis
### Critical Gaps (Block Implementation)
- {gap}: {what's needed}
### Important Gaps (Should Address)
- {gap}: {what's needed}
### Nice-to-Have Gaps
- {gap}: {what's needed}
## Remediation Plan
### Before Implementation (Must Do)
1. {action}: {description}
### During Implementation (Add to Spec)
1. {action}: {description}
### Post-Implementation (Follow Up)
1. {action}: {description}
## Recommendation
{Ready to implement / Needs spec updates first / Needs major revision}
Save the report as .ai/specs/analysis/ANALYSIS-{spec-id}.md.
| Task | Agent Type | When |
|---|---|---|
| Explore existing code for BC impact | Explore | Always — scan for existing event IDs, spot IDs, API routes, types |
| Read multiple AGENTS.md files | Explore | When spec touches 3+ modules |
| Scan for affected test files | Explore | Check which tests might break |
| Analyze entity/migration impact | general-purpose | When spec includes data model changes |
Launch parallel Explore agents for independent code areas (events, API routes, widgets, types).
.ai/specs/analysis/.ai/lessons.md for known pitfalls relevant to the spec's domain