diff --git a/.claude/commands/speckit.retro.analyze.md b/.claude/commands/speckit.retro.analyze.md new file mode 100644 index 00000000..ceb6c7be --- /dev/null +++ b/.claude/commands/speckit.retro.analyze.md @@ -0,0 +1,472 @@ +--- +description: Perform retrospective analysis on completed specs to extract shared constraints + and improve constitution, templates, and checklists through self-improvement. +--- + + + + +## User Input + +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). + +## Goal + +Analyze completed specs to identify cross-cutting patterns, constraints, and lessons learned, then propose improvements to the project's constitution, templates, and checklists. This enables speckit to continuously improve itself based on real implementation experience. + +## Operating Philosophy + +**Self-Improvement Loop**: Each completed spec is a learning opportunity. The retro process distills implementation experience into reusable governance rules, better templates, and quality gates that make future specs higher quality with less ambiguity. + +**Constitution-First**: The constitution is the only artifact loaded by all future specs. Extracting shared constraints into the constitution has maximum leverage—it improves every subsequent spec automatically. + +**No New Artifacts**: This command does NOT create summary.md or other new file types. It strengthens existing infrastructure (constitution, templates, checklists) that speckit commands already use. + +## Execution Steps + +### 1. Identify Completed Specs + +Ask the user which specs to analyze. Suggested formats: +- Range: "015-019" (analyze specs 015 through 019) +- List: "015,017,019" (analyze specific specs) +- All: "all" (analyze all specs in /specs/) + +Parse the input and build a list of spec directories to analyze. + +### 2. Cluster Specs by Topic (if analyzing 5+ specs) + +**Skip this step if analyzing fewer than 5 specs.** + +For large-scale analysis (5+ specs), automatically cluster specs by topic before pattern extraction to ensure high-quality, focused proposals. + +#### 2.1 Load Minimal Context for Clustering + +For each spec, read only: +- **spec.md**: First 50 lines (Overview/Context section) +- **plan.md**: Technology & Architecture Constraints section + +Extract key indicators: +- Primary components mentioned (daemon, proxy, CLI, web UI, config, TUI, etc.) +- Technology stack (Go packages, React, SQLite, etc.) +- Feature category keywords (stability, routing, monitoring, migration, etc.) + +#### 2.2 Perform Automatic Clustering + +Group specs by similarity using these heuristics: + +**Component-based clustering** (adapt to your project structure): +- Backend/API: specs mentioning server, API endpoints, business logic, data access +- Frontend/UI: specs mentioning UI components, user interactions, styling, client-side logic +- CLI/Tooling: specs mentioning command-line interface, scripts, automation +- Infrastructure: specs mentioning deployment, configuration, monitoring, logging +- Testing & Quality: specs mentioning test coverage, CI/CD, integration tests + +**Feature-based clustering** (if component clustering produces groups >8 specs): +- Stability & Reliability: error handling, recovery, resilience, fault tolerance +- Performance & Scalability: optimization, caching, concurrency, load handling +- Security & Privacy: authentication, authorization, data protection, validation +- Data & Storage: database, schema, migration, persistence +- User Experience: usability, accessibility, responsiveness, feedback + +#### 2.3 Present Clustering Results + +Output clustering summary: + +```markdown +## Spec Clustering Results + +Analyzed 20 specs, grouped into 4 clusters: + +### Group 1: Backend & API (7 specs) +- 015-user-authentication +- 017-api-rate-limiting +- 018-data-validation +- 019-caching-strategy +- 020-error-handling +- ... + +**Focus areas**: API design, data processing, error handling, performance + +### Group 2: Frontend & UI (5 specs) +- 003-responsive-layout +- 011-form-validation +- 016-accessibility-improvements +- ... + +**Focus areas**: Component design, user interactions, styling, accessibility + +### Group 3: Infrastructure & Deployment (4 specs) +- 005-logging-system +- 006-monitoring-dashboard +- 008-ci-cd-pipeline +- ... + +**Focus areas**: Observability, deployment automation, configuration management + +### Group 4: Testing & Quality (4 specs) +- 008-integration-tests +- ... + +**Focus areas**: Test coverage, quality gates, automated testing +``` + +#### 2.4 Ask User to Select Groups + +Present options: + +``` +Which groups would you like to analyze? +- [ ] Group 1: Backend & API (7 specs) +- [ ] Group 2: Frontend & UI (5 specs) +- [ ] Group 3: Infrastructure & Deployment (4 specs) +- [ ] Group 4: Testing & Quality (4 specs) +- [ ] All groups (analyze each separately, generate per-group proposals) +- [ ] Skip clustering (analyze all specs together) +``` + +Wait for user selection before proceeding. + +**If user selects multiple groups**: Analyze each group independently and generate separate proposal sections for each. + +**If user selects "Skip clustering"**: Proceed with all specs in a single analysis (may produce lower-quality cross-domain proposals). + +### 3. Load Spec Artifacts + +For each spec in the selected group(s), load: + +**From spec.md**: +- Functional requirements +- Non-functional requirements +- User stories +- Edge cases + +**From plan.md**: +- Architecture decisions and rationale +- Technology choices +- Constitution Check section (violations, complexity justifications) +- Phase breakdown + +**From tasks.md**: +- Task structure and organization patterns +- Dependency patterns +- Parallelization markers + +**From checklists/** (if exists): +- Quality dimensions checked +- Recurring validation patterns + +**From implementation** (if merged): +- Check git log for the feature branch to understand what was actually built +- Look for deviations between plan and implementation + +### 3. Pattern Extraction + +Analyze loaded specs across these dimensions: + +#### A. Shared Constraints (Constitution Candidates) + +Identify rules that appear across multiple specs: +- Technology choices that became de facto standards +- Architecture patterns repeatedly used +- Performance/security requirements that recur +- Testing strategies applied consistently +- Forbidden patterns that caused issues + +**Example**: If 3+ specs all avoid nested API responses beyond 3 levels, that's a constraint worth codifying. + +#### B. Template Gaps + +Identify sections frequently added manually that should be in templates: +- Missing sections in spec-template.md (e.g., "Performance Considerations") +- Missing phases in plan-template.md +- Missing task categories in tasks-template.md + +**Example**: If every spec adds a "Migration Strategy" section, add it to spec-template. + +#### C. Quality Gate Patterns + +Identify validation checks that should become default checklists: +- Security checks repeatedly needed +- Performance validation patterns +- UX quality dimensions +- API design principles + +**Example**: If multiple specs check "rate limiting for batch operations", add it to a default checklist. + +#### D. Constitution Violations + +Review Constitution Check sections across specs: +- Which principles are frequently violated? +- Are violations justified (complexity trade-offs) or avoidable? +- Do violation patterns suggest the principle needs refinement? + +**Example**: If Principle II is violated in 5 specs with similar justifications, the principle may need adjustment. + +#### E. Implementation Deviations + +Compare plans vs actual implementation: +- What changed during implementation and why? +- Were there recurring surprises or unknowns? +- Did certain types of tasks consistently take longer than expected? + +**Example**: If integration tasks consistently reveal missing error handling, add "error handling strategy" to plan-template. + +### 4. Generate Improvement Proposals + +**If analyzing multiple groups**: Generate separate proposal sections for each group with clear group headers. + +**If analyzing a single group or all specs together**: Generate a unified proposal. + +Output a structured proposal document with three sections per group: + +#### Proposed Constitution Amendments + +For each proposed amendment: +- **Type**: New principle | Principle modification | New constraint +- **Rationale**: Which specs demonstrate this pattern (cite spec numbers) +- **Proposed Text**: Exact wording to add/modify +- **Impact**: Which future specs will benefit +- **Version Bump**: MAJOR | MINOR | PATCH (per constitution governance rules) + +**Format** (for multi-group analysis): +```markdown +## Group 1: Backend & API - Improvement Proposals + +### Constitution Amendments + +#### Amendment 1.1: API Response Time Limits + +**Type**: New constraint (add to "Technology & Architecture Constraints") + +**Rationale**: Specs 017, 019 both implemented timeout mechanisms (10-second API response limit). This pattern should be codified to ensure consistent user experience. + +**Proposed Text**: +> - **API Response Time**: All API endpoints MUST respond within 10 seconds or return a timeout error. Long-running operations MUST use async patterns with status polling. + +**Impact**: Future API-related specs will include timeout handling from the planning phase. + +**Version Bump**: MINOR (new constraint) + +### Template Updates + +#### Template Update 1.1: Add Error Handling Strategy to plan-template.md + +**Template**: `.specify/templates/plan-template.md` + +**Change Type**: Add section + +**Rationale**: Specs 017, 019, 020 all added "Error Handling Strategy" sections manually for backend features. + +**Proposed Diff**: +```diff ++ ## Error Handling Strategy (for backend/API features) ++ ++ - Error classification (client errors, server errors, transient failures) ++ - Retry logic and backoff strategy ++ - Error response format and status codes ++ - Logging and monitoring for errors +``` + +### Checklist Additions + +#### Checklist Addition 1.1: API Design Checklist + +**Checklist**: Create `.specify/templates/api-design-checklist-template.md` + +**Items**: +- [ ] CHK-API-001: All endpoints have timeout handling +- [ ] CHK-API-002: Error responses follow consistent format +- [ ] CHK-API-003: Rate limiting implemented for resource-intensive endpoints +- [ ] CHK-API-004: Input validation covers all required fields +- [ ] CHK-API-005: API documentation includes error codes and examples + +**Rationale**: Specs 017, 019 both needed these checks. Creating a dedicated API design checklist catches these requirements during planning. + +--- + +## Group 2: Frontend & UI - Improvement Proposals + +### Constitution Amendments + +#### Amendment 2.1: Accessibility Standards + +... +``` + +**Format** (for single-group or unified analysis): +```markdown +### Amendment 1: API Response Nesting Limit + +**Type**: New constraint (add to "Technology & Architecture Constraints") + +**Rationale**: Specs 015, 017, 019 all independently limited API response nesting to 3 levels for performance and client parsing simplicity. This pattern should be codified. + +**Proposed Text**: +> - **API Design**: Response bodies MUST NOT nest objects deeper than 3 levels. Use flat structures with references (IDs) for deep relationships. + +**Impact**: Prevents future specs from creating deeply nested APIs that cause client-side parsing issues. + +**Version Bump**: MINOR (new constraint) +``` + +#### Proposed Template Updates + +For each template update: +- **Template**: Which template file +- **Change Type**: Add section | Modify section | Remove section +- **Rationale**: Which specs needed this manually +- **Proposed Diff**: Show before/after + +**Format**: +```markdown +### Template Update 1: Add Performance Considerations to plan-template.md + +**Template**: `.specify/templates/plan-template.md` + +**Change Type**: Add section + +**Rationale**: Specs 016, 017, 018, 019 all added "Performance Considerations" sections manually. This should be a standard plan section. + +**Proposed Diff**: +```diff ++ ## Performance Considerations ++ ++ - Expected load characteristics ++ - Performance targets (latency, throughput) ++ - Bottleneck analysis ++ - Optimization strategy +``` +``` + +#### Proposed Checklist Additions + +For each checklist addition: +- **Checklist**: Which checklist file (or new checklist to create) +- **Items**: New checklist items to add +- **Rationale**: Which specs would have caught issues earlier + +**Format**: +```markdown +### Checklist Addition 1: Rate Limiting Check + +**Checklist**: `.specify/templates/checklist-template.md` (or create `api-checklist-template.md`) + +**Items**: +- [ ] CHK-API-001: Batch operations have rate limiting +- [ ] CHK-API-002: Rate limit errors return 429 with Retry-After header +- [ ] CHK-API-003: Rate limits documented in API contracts + +**Rationale**: Specs 016, 019 both discovered missing rate limiting during implementation. Adding this to default API checklist catches it during planning. +``` + +### 5. Archive Completed Specs (Optional) + +After extracting improvements, optionally archive the analyzed specs: + +Ask user: "Would you like to archive these specs? This will move original files to `specs/.archive/[NNN]-feature-name/` to reduce future token usage." + +If yes: +- Create `specs/.archive/` directory if it doesn't exist +- For each analyzed spec: + - Move entire spec directory to `.archive/` + - Leave a minimal index file at original location (optional) + +**Minimal index format** (if user wants it): +```markdown +# [NNN] - [Feature Name] (Archived) + +Archived: [date] +Location: `specs/.archive/[NNN]-feature-name/` +Constitution updates: [list amendment numbers from retro] +``` + +### 6. User Review and Approval + +Present the complete proposal and ask: + +"Review the proposed improvements above. Which changes would you like to apply?" + +Options: +- [ ] Apply all constitution amendments +- [ ] Apply all template updates +- [ ] Apply all checklist additions +- [ ] Apply selected items (specify which) +- [ ] Save proposal for later review +- [ ] Cancel (no changes) + +### 7. Apply Approved Changes + +For each approved change: + +**Constitution amendments**: +1. Read current `.specify/memory/constitution.md` +2. Apply the amendment +3. Update version number per governance rules +4. Update Sync Impact Report (HTML comment at top) +5. Write updated constitution + +**Template updates**: +1. Read the template file +2. Apply the diff +3. Write updated template + +**Checklist additions**: +1. Read or create the checklist template +2. Add new items with proper CHK-### IDs +3. Write updated checklist + +### 8. Generate Retro Summary + +Output a concise summary: + +```markdown +## Retro Summary + +**Specs Analyzed**: [list with group breakdown if applicable] +**Groups**: [number of groups, or "unified analysis"] +**Patterns Identified**: [count per group if applicable] +**Changes Applied**: +- Constitution: [count] amendments (version [old] → [new]) +- Templates: [count] updates +- Checklists: [count] additions + +**Per-Group Breakdown** (if multi-group analysis): +- Group 1 (Backend & API): [X] amendments, [Y] template updates, [Z] checklist items +- Group 2 (Frontend & UI): [X] amendments, [Y] template updates, [Z] checklist items +- ... + +**Next Steps**: +- New specs will automatically benefit from updated constitution and templates +- Existing in-progress specs may want to incorporate new checklist items +- Consider running retro again after completing next 5-10 specs +``` + +## Operating Principles + +### Context Efficiency + +- **Progressive loading**: Load specs incrementally, not all at once +- **Pattern-focused**: Extract high-signal patterns, not exhaustive documentation +- **Minimal output**: Proposals should be concise and actionable + +### Analysis Guidelines + +- **Evidence-based**: Every proposal must cite specific specs as evidence +- **Cross-spec patterns only**: Don't propose rules based on a single spec (minimum 2-3 specs showing the same pattern) +- **Respect constitution governance**: Follow versioning and amendment rules +- **No speculation**: Only propose constraints actually demonstrated in completed specs +- **Group-focused proposals**: When analyzing multiple groups, ensure proposals are relevant to the group's domain (don't mix daemon constraints with web UI constraints) + +### Safety + +- **User approval required**: Never auto-apply constitution changes +- **Preserve originals**: Archive moves files, doesn't delete them +- **Reversible**: All changes are git-tracked and can be reverted + +## Context + +$ARGUMENTS \ No newline at end of file diff --git a/.claude/commands/speckit.retro.md b/.claude/commands/speckit.retro.md new file mode 100644 index 00000000..ceb6c7be --- /dev/null +++ b/.claude/commands/speckit.retro.md @@ -0,0 +1,472 @@ +--- +description: Perform retrospective analysis on completed specs to extract shared constraints + and improve constitution, templates, and checklists through self-improvement. +--- + + + + +## User Input + +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). + +## Goal + +Analyze completed specs to identify cross-cutting patterns, constraints, and lessons learned, then propose improvements to the project's constitution, templates, and checklists. This enables speckit to continuously improve itself based on real implementation experience. + +## Operating Philosophy + +**Self-Improvement Loop**: Each completed spec is a learning opportunity. The retro process distills implementation experience into reusable governance rules, better templates, and quality gates that make future specs higher quality with less ambiguity. + +**Constitution-First**: The constitution is the only artifact loaded by all future specs. Extracting shared constraints into the constitution has maximum leverage—it improves every subsequent spec automatically. + +**No New Artifacts**: This command does NOT create summary.md or other new file types. It strengthens existing infrastructure (constitution, templates, checklists) that speckit commands already use. + +## Execution Steps + +### 1. Identify Completed Specs + +Ask the user which specs to analyze. Suggested formats: +- Range: "015-019" (analyze specs 015 through 019) +- List: "015,017,019" (analyze specific specs) +- All: "all" (analyze all specs in /specs/) + +Parse the input and build a list of spec directories to analyze. + +### 2. Cluster Specs by Topic (if analyzing 5+ specs) + +**Skip this step if analyzing fewer than 5 specs.** + +For large-scale analysis (5+ specs), automatically cluster specs by topic before pattern extraction to ensure high-quality, focused proposals. + +#### 2.1 Load Minimal Context for Clustering + +For each spec, read only: +- **spec.md**: First 50 lines (Overview/Context section) +- **plan.md**: Technology & Architecture Constraints section + +Extract key indicators: +- Primary components mentioned (daemon, proxy, CLI, web UI, config, TUI, etc.) +- Technology stack (Go packages, React, SQLite, etc.) +- Feature category keywords (stability, routing, monitoring, migration, etc.) + +#### 2.2 Perform Automatic Clustering + +Group specs by similarity using these heuristics: + +**Component-based clustering** (adapt to your project structure): +- Backend/API: specs mentioning server, API endpoints, business logic, data access +- Frontend/UI: specs mentioning UI components, user interactions, styling, client-side logic +- CLI/Tooling: specs mentioning command-line interface, scripts, automation +- Infrastructure: specs mentioning deployment, configuration, monitoring, logging +- Testing & Quality: specs mentioning test coverage, CI/CD, integration tests + +**Feature-based clustering** (if component clustering produces groups >8 specs): +- Stability & Reliability: error handling, recovery, resilience, fault tolerance +- Performance & Scalability: optimization, caching, concurrency, load handling +- Security & Privacy: authentication, authorization, data protection, validation +- Data & Storage: database, schema, migration, persistence +- User Experience: usability, accessibility, responsiveness, feedback + +#### 2.3 Present Clustering Results + +Output clustering summary: + +```markdown +## Spec Clustering Results + +Analyzed 20 specs, grouped into 4 clusters: + +### Group 1: Backend & API (7 specs) +- 015-user-authentication +- 017-api-rate-limiting +- 018-data-validation +- 019-caching-strategy +- 020-error-handling +- ... + +**Focus areas**: API design, data processing, error handling, performance + +### Group 2: Frontend & UI (5 specs) +- 003-responsive-layout +- 011-form-validation +- 016-accessibility-improvements +- ... + +**Focus areas**: Component design, user interactions, styling, accessibility + +### Group 3: Infrastructure & Deployment (4 specs) +- 005-logging-system +- 006-monitoring-dashboard +- 008-ci-cd-pipeline +- ... + +**Focus areas**: Observability, deployment automation, configuration management + +### Group 4: Testing & Quality (4 specs) +- 008-integration-tests +- ... + +**Focus areas**: Test coverage, quality gates, automated testing +``` + +#### 2.4 Ask User to Select Groups + +Present options: + +``` +Which groups would you like to analyze? +- [ ] Group 1: Backend & API (7 specs) +- [ ] Group 2: Frontend & UI (5 specs) +- [ ] Group 3: Infrastructure & Deployment (4 specs) +- [ ] Group 4: Testing & Quality (4 specs) +- [ ] All groups (analyze each separately, generate per-group proposals) +- [ ] Skip clustering (analyze all specs together) +``` + +Wait for user selection before proceeding. + +**If user selects multiple groups**: Analyze each group independently and generate separate proposal sections for each. + +**If user selects "Skip clustering"**: Proceed with all specs in a single analysis (may produce lower-quality cross-domain proposals). + +### 3. Load Spec Artifacts + +For each spec in the selected group(s), load: + +**From spec.md**: +- Functional requirements +- Non-functional requirements +- User stories +- Edge cases + +**From plan.md**: +- Architecture decisions and rationale +- Technology choices +- Constitution Check section (violations, complexity justifications) +- Phase breakdown + +**From tasks.md**: +- Task structure and organization patterns +- Dependency patterns +- Parallelization markers + +**From checklists/** (if exists): +- Quality dimensions checked +- Recurring validation patterns + +**From implementation** (if merged): +- Check git log for the feature branch to understand what was actually built +- Look for deviations between plan and implementation + +### 3. Pattern Extraction + +Analyze loaded specs across these dimensions: + +#### A. Shared Constraints (Constitution Candidates) + +Identify rules that appear across multiple specs: +- Technology choices that became de facto standards +- Architecture patterns repeatedly used +- Performance/security requirements that recur +- Testing strategies applied consistently +- Forbidden patterns that caused issues + +**Example**: If 3+ specs all avoid nested API responses beyond 3 levels, that's a constraint worth codifying. + +#### B. Template Gaps + +Identify sections frequently added manually that should be in templates: +- Missing sections in spec-template.md (e.g., "Performance Considerations") +- Missing phases in plan-template.md +- Missing task categories in tasks-template.md + +**Example**: If every spec adds a "Migration Strategy" section, add it to spec-template. + +#### C. Quality Gate Patterns + +Identify validation checks that should become default checklists: +- Security checks repeatedly needed +- Performance validation patterns +- UX quality dimensions +- API design principles + +**Example**: If multiple specs check "rate limiting for batch operations", add it to a default checklist. + +#### D. Constitution Violations + +Review Constitution Check sections across specs: +- Which principles are frequently violated? +- Are violations justified (complexity trade-offs) or avoidable? +- Do violation patterns suggest the principle needs refinement? + +**Example**: If Principle II is violated in 5 specs with similar justifications, the principle may need adjustment. + +#### E. Implementation Deviations + +Compare plans vs actual implementation: +- What changed during implementation and why? +- Were there recurring surprises or unknowns? +- Did certain types of tasks consistently take longer than expected? + +**Example**: If integration tasks consistently reveal missing error handling, add "error handling strategy" to plan-template. + +### 4. Generate Improvement Proposals + +**If analyzing multiple groups**: Generate separate proposal sections for each group with clear group headers. + +**If analyzing a single group or all specs together**: Generate a unified proposal. + +Output a structured proposal document with three sections per group: + +#### Proposed Constitution Amendments + +For each proposed amendment: +- **Type**: New principle | Principle modification | New constraint +- **Rationale**: Which specs demonstrate this pattern (cite spec numbers) +- **Proposed Text**: Exact wording to add/modify +- **Impact**: Which future specs will benefit +- **Version Bump**: MAJOR | MINOR | PATCH (per constitution governance rules) + +**Format** (for multi-group analysis): +```markdown +## Group 1: Backend & API - Improvement Proposals + +### Constitution Amendments + +#### Amendment 1.1: API Response Time Limits + +**Type**: New constraint (add to "Technology & Architecture Constraints") + +**Rationale**: Specs 017, 019 both implemented timeout mechanisms (10-second API response limit). This pattern should be codified to ensure consistent user experience. + +**Proposed Text**: +> - **API Response Time**: All API endpoints MUST respond within 10 seconds or return a timeout error. Long-running operations MUST use async patterns with status polling. + +**Impact**: Future API-related specs will include timeout handling from the planning phase. + +**Version Bump**: MINOR (new constraint) + +### Template Updates + +#### Template Update 1.1: Add Error Handling Strategy to plan-template.md + +**Template**: `.specify/templates/plan-template.md` + +**Change Type**: Add section + +**Rationale**: Specs 017, 019, 020 all added "Error Handling Strategy" sections manually for backend features. + +**Proposed Diff**: +```diff ++ ## Error Handling Strategy (for backend/API features) ++ ++ - Error classification (client errors, server errors, transient failures) ++ - Retry logic and backoff strategy ++ - Error response format and status codes ++ - Logging and monitoring for errors +``` + +### Checklist Additions + +#### Checklist Addition 1.1: API Design Checklist + +**Checklist**: Create `.specify/templates/api-design-checklist-template.md` + +**Items**: +- [ ] CHK-API-001: All endpoints have timeout handling +- [ ] CHK-API-002: Error responses follow consistent format +- [ ] CHK-API-003: Rate limiting implemented for resource-intensive endpoints +- [ ] CHK-API-004: Input validation covers all required fields +- [ ] CHK-API-005: API documentation includes error codes and examples + +**Rationale**: Specs 017, 019 both needed these checks. Creating a dedicated API design checklist catches these requirements during planning. + +--- + +## Group 2: Frontend & UI - Improvement Proposals + +### Constitution Amendments + +#### Amendment 2.1: Accessibility Standards + +... +``` + +**Format** (for single-group or unified analysis): +```markdown +### Amendment 1: API Response Nesting Limit + +**Type**: New constraint (add to "Technology & Architecture Constraints") + +**Rationale**: Specs 015, 017, 019 all independently limited API response nesting to 3 levels for performance and client parsing simplicity. This pattern should be codified. + +**Proposed Text**: +> - **API Design**: Response bodies MUST NOT nest objects deeper than 3 levels. Use flat structures with references (IDs) for deep relationships. + +**Impact**: Prevents future specs from creating deeply nested APIs that cause client-side parsing issues. + +**Version Bump**: MINOR (new constraint) +``` + +#### Proposed Template Updates + +For each template update: +- **Template**: Which template file +- **Change Type**: Add section | Modify section | Remove section +- **Rationale**: Which specs needed this manually +- **Proposed Diff**: Show before/after + +**Format**: +```markdown +### Template Update 1: Add Performance Considerations to plan-template.md + +**Template**: `.specify/templates/plan-template.md` + +**Change Type**: Add section + +**Rationale**: Specs 016, 017, 018, 019 all added "Performance Considerations" sections manually. This should be a standard plan section. + +**Proposed Diff**: +```diff ++ ## Performance Considerations ++ ++ - Expected load characteristics ++ - Performance targets (latency, throughput) ++ - Bottleneck analysis ++ - Optimization strategy +``` +``` + +#### Proposed Checklist Additions + +For each checklist addition: +- **Checklist**: Which checklist file (or new checklist to create) +- **Items**: New checklist items to add +- **Rationale**: Which specs would have caught issues earlier + +**Format**: +```markdown +### Checklist Addition 1: Rate Limiting Check + +**Checklist**: `.specify/templates/checklist-template.md` (or create `api-checklist-template.md`) + +**Items**: +- [ ] CHK-API-001: Batch operations have rate limiting +- [ ] CHK-API-002: Rate limit errors return 429 with Retry-After header +- [ ] CHK-API-003: Rate limits documented in API contracts + +**Rationale**: Specs 016, 019 both discovered missing rate limiting during implementation. Adding this to default API checklist catches it during planning. +``` + +### 5. Archive Completed Specs (Optional) + +After extracting improvements, optionally archive the analyzed specs: + +Ask user: "Would you like to archive these specs? This will move original files to `specs/.archive/[NNN]-feature-name/` to reduce future token usage." + +If yes: +- Create `specs/.archive/` directory if it doesn't exist +- For each analyzed spec: + - Move entire spec directory to `.archive/` + - Leave a minimal index file at original location (optional) + +**Minimal index format** (if user wants it): +```markdown +# [NNN] - [Feature Name] (Archived) + +Archived: [date] +Location: `specs/.archive/[NNN]-feature-name/` +Constitution updates: [list amendment numbers from retro] +``` + +### 6. User Review and Approval + +Present the complete proposal and ask: + +"Review the proposed improvements above. Which changes would you like to apply?" + +Options: +- [ ] Apply all constitution amendments +- [ ] Apply all template updates +- [ ] Apply all checklist additions +- [ ] Apply selected items (specify which) +- [ ] Save proposal for later review +- [ ] Cancel (no changes) + +### 7. Apply Approved Changes + +For each approved change: + +**Constitution amendments**: +1. Read current `.specify/memory/constitution.md` +2. Apply the amendment +3. Update version number per governance rules +4. Update Sync Impact Report (HTML comment at top) +5. Write updated constitution + +**Template updates**: +1. Read the template file +2. Apply the diff +3. Write updated template + +**Checklist additions**: +1. Read or create the checklist template +2. Add new items with proper CHK-### IDs +3. Write updated checklist + +### 8. Generate Retro Summary + +Output a concise summary: + +```markdown +## Retro Summary + +**Specs Analyzed**: [list with group breakdown if applicable] +**Groups**: [number of groups, or "unified analysis"] +**Patterns Identified**: [count per group if applicable] +**Changes Applied**: +- Constitution: [count] amendments (version [old] → [new]) +- Templates: [count] updates +- Checklists: [count] additions + +**Per-Group Breakdown** (if multi-group analysis): +- Group 1 (Backend & API): [X] amendments, [Y] template updates, [Z] checklist items +- Group 2 (Frontend & UI): [X] amendments, [Y] template updates, [Z] checklist items +- ... + +**Next Steps**: +- New specs will automatically benefit from updated constitution and templates +- Existing in-progress specs may want to incorporate new checklist items +- Consider running retro again after completing next 5-10 specs +``` + +## Operating Principles + +### Context Efficiency + +- **Progressive loading**: Load specs incrementally, not all at once +- **Pattern-focused**: Extract high-signal patterns, not exhaustive documentation +- **Minimal output**: Proposals should be concise and actionable + +### Analysis Guidelines + +- **Evidence-based**: Every proposal must cite specific specs as evidence +- **Cross-spec patterns only**: Don't propose rules based on a single spec (minimum 2-3 specs showing the same pattern) +- **Respect constitution governance**: Follow versioning and amendment rules +- **No speculation**: Only propose constraints actually demonstrated in completed specs +- **Group-focused proposals**: When analyzing multiple groups, ensure proposals are relevant to the group's domain (don't mix daemon constraints with web UI constraints) + +### Safety + +- **User approval required**: Never auto-apply constitution changes +- **Preserve originals**: Archive moves files, doesn't delete them +- **Reversible**: All changes are git-tracked and can be reverted + +## Context + +$ARGUMENTS \ No newline at end of file diff --git a/.gitignore b/.gitignore index 2c31308d..2f4abf35 100644 --- a/.gitignore +++ b/.gitignore @@ -10,6 +10,8 @@ web/dist/ internal/web/dist/ bin/ web/coverage/ +.specify/extensions/.cache/ +.specify/extensions/.backup/ # Go *.exe diff --git a/.specify/extensions.yml b/.specify/extensions.yml new file mode 100644 index 00000000..d6823bf0 --- /dev/null +++ b/.specify/extensions.yml @@ -0,0 +1,4 @@ +installed: [] +settings: + auto_execute_hooks: true +hooks: {} diff --git a/.specify/extensions/.registry b/.specify/extensions/.registry new file mode 100644 index 00000000..969c63f1 --- /dev/null +++ b/.specify/extensions/.registry @@ -0,0 +1,22 @@ +{ + "schema_version": "1.0", + "extensions": { + "retro": { + "version": "1.0.2", + "source": "local", + "manifest_hash": "sha256:07a038a57aa8125331ff346c2562976a1f7be5a3f0d6f041c8c4b72fd1ae426e", + "enabled": true, + "registered_commands": { + "claude": [ + "speckit.retro.analyze", + "speckit.retro" + ], + "copilot": [ + "speckit.retro.analyze", + "speckit.retro" + ] + }, + "installed_at": "2026-03-10T11:02:55.438106+00:00" + } + } +} \ No newline at end of file diff --git a/.specify/extensions/retro/.github/README.md b/.specify/extensions/retro/.github/README.md new file mode 100644 index 00000000..31866738 --- /dev/null +++ b/.specify/extensions/retro/.github/README.md @@ -0,0 +1,51 @@ +# speckit-retro-extension + +Spec-kit extension for retrospective analysis and continuous self-improvement. + +## Quick Links + +- [Installation & Usage](README.md) +- [Changelog](CHANGELOG.md) +- [License](LICENSE) + +## Structure + +``` +speckit-retro-extension/ +├── extension.yml # Extension manifest +├── README.md # Documentation +├── LICENSE # MIT License +├── CHANGELOG.md # Version history +└── commands/ + └── retro.md # /speckit.retro command implementation +``` + +## Local Testing + +To test this extension locally before publishing: + +```bash +cd ~/Code/speckit-retro-extension +specify extension add --from . +``` + +Then in your spec-kit project: + +```bash +/speckit.retro 015-019 +``` + +## Publishing + +1. Update version in `extension.yml` +2. Update `CHANGELOG.md` +3. Commit changes +4. Create git tag: `git tag v1.0.0` +5. Push tag: `git push origin v1.0.0` +6. Create GitHub release from tag + +Users can then install via: + +```bash +specify extension add --from https://github.com/dopejs/speckit-retro-extension +``` diff --git a/.specify/extensions/retro/.github/workflows/release.yml b/.specify/extensions/retro/.github/workflows/release.yml new file mode 100644 index 00000000..4ec9ba65 --- /dev/null +++ b/.specify/extensions/retro/.github/workflows/release.yml @@ -0,0 +1,44 @@ +name: Release + +on: + push: + tags: + - 'v*' + +permissions: + contents: write + +jobs: + release: + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Create release archive + run: | + VERSION=${GITHUB_REF#refs/tags/} + zip -r speckit-retro-extension-${VERSION}.zip . \ + -x ".git/*" \ + -x ".github/*" \ + -x "*.zip" + + - name: Create GitHub Release + uses: softprops/action-gh-release@v1 + with: + files: speckit-retro-extension-*.zip + generate_release_notes: true + body: | + ## Installation + + ```bash + specify extension add retro --from https://github.com/dopejs/speckit-retro-extension/archive/refs/tags/${{ github.ref_name }}.zip + ``` + + ## Usage + + ```bash + /speckit.retro 015-019 + ``` + + See [README](https://github.com/dopejs/speckit-retro-extension#readme) for full documentation. diff --git a/.specify/extensions/retro/CHANGELOG.md b/.specify/extensions/retro/CHANGELOG.md new file mode 100644 index 00000000..7c553b86 --- /dev/null +++ b/.specify/extensions/retro/CHANGELOG.md @@ -0,0 +1,35 @@ +# Changelog + +All notable changes to the Spec Retrospective & Self-Improvement Extension will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [1.0.2] - 2026-03-10 + +### Added +- GitHub Action for automated release packaging + +## [1.0.1] - 2026-03-10 + +### Fixed +- Command naming to follow `speckit.{extension}.{command}` pattern +- Command is now `speckit.retro.analyze` with alias `speckit.retro` + +## [1.0.0] - 2026-03-10 + +### Added +- Initial release of spec retrospective extension +- Automatic clustering for 5+ specs by component and feature +- Pattern extraction across multiple dimensions: + - Shared constraints (constitution candidates) + - Template gaps (missing sections) + - Quality gate patterns (checklist items) + - Constitution violations (principle refinements) + - Implementation deviations (process improvements) +- Evidence-based proposals with spec citations +- Multi-group analysis with separate proposals per group +- User approval workflow for applying changes +- Optional spec archival to reduce token usage +- Constitution versioning support (MAJOR/MINOR/PATCH) +- Progressive loading for token efficiency diff --git a/.specify/extensions/retro/LICENSE b/.specify/extensions/retro/LICENSE new file mode 100644 index 00000000..02a1b1cd --- /dev/null +++ b/.specify/extensions/retro/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 John + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/.specify/extensions/retro/README.md b/.specify/extensions/retro/README.md new file mode 100644 index 00000000..22aff0bf --- /dev/null +++ b/.specify/extensions/retro/README.md @@ -0,0 +1,181 @@ +# Spec Retrospective & Self-Improvement Extension + +A spec-kit extension that enables continuous improvement by analyzing completed specs to extract shared constraints, patterns, and lessons learned, then proposing improvements to your project's constitution, templates, and checklists. + +## Overview + +As your project accumulates specs, this extension helps you: + +- **Extract cross-cutting patterns** from completed implementations +- **Identify shared constraints** that should be codified in your constitution +- **Discover template gaps** where manual additions are repeatedly needed +- **Build quality checklists** based on recurring validation needs +- **Reduce token usage** by archiving analyzed specs after extracting their lessons + +## Philosophy + +**Self-Improvement Loop**: Each completed spec is a learning opportunity. The retro process distills implementation experience into reusable governance rules, better templates, and quality gates that make future specs higher quality with less ambiguity. + +**Constitution-First**: The constitution is the only artifact loaded by all future specs. Extracting shared constraints into the constitution has maximum leverage—it improves every subsequent spec automatically. + +**No New Artifacts**: This extension does NOT create summary.md or other new file types. It strengthens existing infrastructure (constitution, templates, checklists) that spec-kit commands already use. + +## Installation + +### From GitHub (recommended) + +```bash +specify extension add --from https://github.com/dopejs/speckit-retro-extension +``` + +### From Local Path (for development) + +```bash +specify extension add --from /path/to/speckit-retro-extension +``` + +## Usage + +### Basic Usage + +Analyze a range of completed specs: + +```bash +/speckit.retro 015-019 +``` + +Analyze specific specs: + +```bash +/speckit.retro 015,017,019 +``` + +Analyze all specs: + +```bash +/speckit.retro all +``` + +### Workflow + +1. **Identify specs** — Specify which completed specs to analyze +2. **Automatic clustering** — For 5+ specs, automatically groups by topic/component +3. **Select groups** — Choose which groups to analyze (or analyze all) +4. **Pattern extraction** — Identifies cross-spec patterns in: + - Shared constraints (constitution candidates) + - Template gaps (missing sections) + - Quality gates (checklist items) + - Constitution violations (principle refinements) + - Implementation deviations (process improvements) +5. **Review proposals** — Structured improvement proposals with evidence +6. **Apply changes** — Select which improvements to apply +7. **Optional archival** — Move analyzed specs to `.archive/` to reduce token usage + +### Example Output + +```markdown +## Group 1: Backend & API - Improvement Proposals + +### Constitution Amendments + +#### Amendment 1.1: API Response Time Limits + +**Type**: New constraint +**Rationale**: Specs 017, 019 both implemented 10-second timeout mechanisms +**Proposed Text**: All API endpoints MUST respond within 10 seconds... +**Version Bump**: MINOR + +### Template Updates + +#### Template Update 1.1: Add Error Handling Strategy + +**Template**: plan-template.md +**Rationale**: Specs 017, 019, 020 all added this section manually +**Proposed Diff**: [shows exact changes] + +### Checklist Additions + +#### Checklist Addition 1.1: API Design Checklist + +**Items**: +- [ ] CHK-API-001: All endpoints have timeout handling +- [ ] CHK-API-002: Error responses follow consistent format +... +``` + +## Features + +### Automatic Clustering (5+ specs) + +When analyzing many specs, the extension automatically clusters them by: + +**Component-based**: Backend/API, Frontend/UI, CLI/Tooling, Infrastructure, Testing +**Feature-based**: Stability, Performance, Security, Data, User Experience + +This ensures proposals are focused and domain-specific rather than mixing unrelated constraints. + +### Evidence-Based Proposals + +Every proposal cites specific specs as evidence. Minimum 2-3 specs must show the same pattern before it's proposed as a shared constraint. + +### Safe Application + +- User approval required for all changes +- Constitution versioning follows governance rules (MAJOR/MINOR/PATCH) +- All changes are git-tracked and reversible +- Original specs preserved in `.archive/` if archived + +### Token Efficiency + +- Progressive loading (specs loaded incrementally) +- Minimal context extraction (only relevant sections) +- Optional archival reduces future token usage by 90%+ + +## When to Run Retro + +**Recommended cadence**: After completing every 5-10 specs + +**Good times to run**: +- After a major feature milestone +- Before starting a new development phase +- When you notice repeated patterns across recent specs +- When constitution feels outdated or incomplete + +**Signs you need retro**: +- Specs repeatedly add the same manual sections +- Similar quality issues appear across multiple specs +- Constitution violations have similar justifications +- Token usage is growing due to many historical specs + +## Requirements + +- spec-kit >= 0.1.0 +- Existing spec-kit project with completed specs +- Constitution file at `.specify/memory/constitution.md` + +## Configuration + +No configuration needed. The extension works with your existing spec-kit setup. + +## Contributing + +Contributions welcome! Please: + +1. Fork the repository +2. Create a feature branch +3. Test on real projects +4. Submit a pull request + +## License + +MIT License - see LICENSE file for details + +## Support + +- Issues: https://github.com/dopejs/speckit-retro-extension/issues +- Discussions: https://github.com/dopejs/speckit-retro-extension/discussions + +## Related + +- [spec-kit](https://github.com/github/spec-kit) - The core spec-kit framework +- [Extension Development Guide](https://github.com/github/spec-kit/blob/main/extensions/EXTENSION-DEVELOPMENT-GUIDE.md) diff --git a/.specify/extensions/retro/commands/analyze.md b/.specify/extensions/retro/commands/analyze.md new file mode 100644 index 00000000..d2fe531e --- /dev/null +++ b/.specify/extensions/retro/commands/analyze.md @@ -0,0 +1,468 @@ +--- +description: Perform retrospective analysis on completed specs to extract shared constraints and improve constitution, templates, and checklists through self-improvement. +--- + +## User Input + +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). + +## Goal + +Analyze completed specs to identify cross-cutting patterns, constraints, and lessons learned, then propose improvements to the project's constitution, templates, and checklists. This enables speckit to continuously improve itself based on real implementation experience. + +## Operating Philosophy + +**Self-Improvement Loop**: Each completed spec is a learning opportunity. The retro process distills implementation experience into reusable governance rules, better templates, and quality gates that make future specs higher quality with less ambiguity. + +**Constitution-First**: The constitution is the only artifact loaded by all future specs. Extracting shared constraints into the constitution has maximum leverage—it improves every subsequent spec automatically. + +**No New Artifacts**: This command does NOT create summary.md or other new file types. It strengthens existing infrastructure (constitution, templates, checklists) that speckit commands already use. + +## Execution Steps + +### 1. Identify Completed Specs + +Ask the user which specs to analyze. Suggested formats: +- Range: "015-019" (analyze specs 015 through 019) +- List: "015,017,019" (analyze specific specs) +- All: "all" (analyze all specs in /specs/) + +Parse the input and build a list of spec directories to analyze. + +### 2. Cluster Specs by Topic (if analyzing 5+ specs) + +**Skip this step if analyzing fewer than 5 specs.** + +For large-scale analysis (5+ specs), automatically cluster specs by topic before pattern extraction to ensure high-quality, focused proposals. + +#### 2.1 Load Minimal Context for Clustering + +For each spec, read only: +- **spec.md**: First 50 lines (Overview/Context section) +- **plan.md**: Technology & Architecture Constraints section + +Extract key indicators: +- Primary components mentioned (daemon, proxy, CLI, web UI, config, TUI, etc.) +- Technology stack (Go packages, React, SQLite, etc.) +- Feature category keywords (stability, routing, monitoring, migration, etc.) + +#### 2.2 Perform Automatic Clustering + +Group specs by similarity using these heuristics: + +**Component-based clustering** (adapt to your project structure): +- Backend/API: specs mentioning server, API endpoints, business logic, data access +- Frontend/UI: specs mentioning UI components, user interactions, styling, client-side logic +- CLI/Tooling: specs mentioning command-line interface, scripts, automation +- Infrastructure: specs mentioning deployment, configuration, monitoring, logging +- Testing & Quality: specs mentioning test coverage, CI/CD, integration tests + +**Feature-based clustering** (if component clustering produces groups >8 specs): +- Stability & Reliability: error handling, recovery, resilience, fault tolerance +- Performance & Scalability: optimization, caching, concurrency, load handling +- Security & Privacy: authentication, authorization, data protection, validation +- Data & Storage: database, schema, migration, persistence +- User Experience: usability, accessibility, responsiveness, feedback + +#### 2.3 Present Clustering Results + +Output clustering summary: + +```markdown +## Spec Clustering Results + +Analyzed 20 specs, grouped into 4 clusters: + +### Group 1: Backend & API (7 specs) +- 015-user-authentication +- 017-api-rate-limiting +- 018-data-validation +- 019-caching-strategy +- 020-error-handling +- ... + +**Focus areas**: API design, data processing, error handling, performance + +### Group 2: Frontend & UI (5 specs) +- 003-responsive-layout +- 011-form-validation +- 016-accessibility-improvements +- ... + +**Focus areas**: Component design, user interactions, styling, accessibility + +### Group 3: Infrastructure & Deployment (4 specs) +- 005-logging-system +- 006-monitoring-dashboard +- 008-ci-cd-pipeline +- ... + +**Focus areas**: Observability, deployment automation, configuration management + +### Group 4: Testing & Quality (4 specs) +- 008-integration-tests +- ... + +**Focus areas**: Test coverage, quality gates, automated testing +``` + +#### 2.4 Ask User to Select Groups + +Present options: + +``` +Which groups would you like to analyze? +- [ ] Group 1: Backend & API (7 specs) +- [ ] Group 2: Frontend & UI (5 specs) +- [ ] Group 3: Infrastructure & Deployment (4 specs) +- [ ] Group 4: Testing & Quality (4 specs) +- [ ] All groups (analyze each separately, generate per-group proposals) +- [ ] Skip clustering (analyze all specs together) +``` + +Wait for user selection before proceeding. + +**If user selects multiple groups**: Analyze each group independently and generate separate proposal sections for each. + +**If user selects "Skip clustering"**: Proceed with all specs in a single analysis (may produce lower-quality cross-domain proposals). + +### 3. Load Spec Artifacts + +For each spec in the selected group(s), load: + +**From spec.md**: +- Functional requirements +- Non-functional requirements +- User stories +- Edge cases + +**From plan.md**: +- Architecture decisions and rationale +- Technology choices +- Constitution Check section (violations, complexity justifications) +- Phase breakdown + +**From tasks.md**: +- Task structure and organization patterns +- Dependency patterns +- Parallelization markers + +**From checklists/** (if exists): +- Quality dimensions checked +- Recurring validation patterns + +**From implementation** (if merged): +- Check git log for the feature branch to understand what was actually built +- Look for deviations between plan and implementation + +### 3. Pattern Extraction + +Analyze loaded specs across these dimensions: + +#### A. Shared Constraints (Constitution Candidates) + +Identify rules that appear across multiple specs: +- Technology choices that became de facto standards +- Architecture patterns repeatedly used +- Performance/security requirements that recur +- Testing strategies applied consistently +- Forbidden patterns that caused issues + +**Example**: If 3+ specs all avoid nested API responses beyond 3 levels, that's a constraint worth codifying. + +#### B. Template Gaps + +Identify sections frequently added manually that should be in templates: +- Missing sections in spec-template.md (e.g., "Performance Considerations") +- Missing phases in plan-template.md +- Missing task categories in tasks-template.md + +**Example**: If every spec adds a "Migration Strategy" section, add it to spec-template. + +#### C. Quality Gate Patterns + +Identify validation checks that should become default checklists: +- Security checks repeatedly needed +- Performance validation patterns +- UX quality dimensions +- API design principles + +**Example**: If multiple specs check "rate limiting for batch operations", add it to a default checklist. + +#### D. Constitution Violations + +Review Constitution Check sections across specs: +- Which principles are frequently violated? +- Are violations justified (complexity trade-offs) or avoidable? +- Do violation patterns suggest the principle needs refinement? + +**Example**: If Principle II is violated in 5 specs with similar justifications, the principle may need adjustment. + +#### E. Implementation Deviations + +Compare plans vs actual implementation: +- What changed during implementation and why? +- Were there recurring surprises or unknowns? +- Did certain types of tasks consistently take longer than expected? + +**Example**: If integration tasks consistently reveal missing error handling, add "error handling strategy" to plan-template. + +### 4. Generate Improvement Proposals + +**If analyzing multiple groups**: Generate separate proposal sections for each group with clear group headers. + +**If analyzing a single group or all specs together**: Generate a unified proposal. + +Output a structured proposal document with three sections per group: + +#### Proposed Constitution Amendments + +For each proposed amendment: +- **Type**: New principle | Principle modification | New constraint +- **Rationale**: Which specs demonstrate this pattern (cite spec numbers) +- **Proposed Text**: Exact wording to add/modify +- **Impact**: Which future specs will benefit +- **Version Bump**: MAJOR | MINOR | PATCH (per constitution governance rules) + +**Format** (for multi-group analysis): +```markdown +## Group 1: Backend & API - Improvement Proposals + +### Constitution Amendments + +#### Amendment 1.1: API Response Time Limits + +**Type**: New constraint (add to "Technology & Architecture Constraints") + +**Rationale**: Specs 017, 019 both implemented timeout mechanisms (10-second API response limit). This pattern should be codified to ensure consistent user experience. + +**Proposed Text**: +> - **API Response Time**: All API endpoints MUST respond within 10 seconds or return a timeout error. Long-running operations MUST use async patterns with status polling. + +**Impact**: Future API-related specs will include timeout handling from the planning phase. + +**Version Bump**: MINOR (new constraint) + +### Template Updates + +#### Template Update 1.1: Add Error Handling Strategy to plan-template.md + +**Template**: `.specify/templates/plan-template.md` + +**Change Type**: Add section + +**Rationale**: Specs 017, 019, 020 all added "Error Handling Strategy" sections manually for backend features. + +**Proposed Diff**: +```diff ++ ## Error Handling Strategy (for backend/API features) ++ ++ - Error classification (client errors, server errors, transient failures) ++ - Retry logic and backoff strategy ++ - Error response format and status codes ++ - Logging and monitoring for errors +``` + +### Checklist Additions + +#### Checklist Addition 1.1: API Design Checklist + +**Checklist**: Create `.specify/templates/api-design-checklist-template.md` + +**Items**: +- [ ] CHK-API-001: All endpoints have timeout handling +- [ ] CHK-API-002: Error responses follow consistent format +- [ ] CHK-API-003: Rate limiting implemented for resource-intensive endpoints +- [ ] CHK-API-004: Input validation covers all required fields +- [ ] CHK-API-005: API documentation includes error codes and examples + +**Rationale**: Specs 017, 019 both needed these checks. Creating a dedicated API design checklist catches these requirements during planning. + +--- + +## Group 2: Frontend & UI - Improvement Proposals + +### Constitution Amendments + +#### Amendment 2.1: Accessibility Standards + +... +``` + +**Format** (for single-group or unified analysis): +```markdown +### Amendment 1: API Response Nesting Limit + +**Type**: New constraint (add to "Technology & Architecture Constraints") + +**Rationale**: Specs 015, 017, 019 all independently limited API response nesting to 3 levels for performance and client parsing simplicity. This pattern should be codified. + +**Proposed Text**: +> - **API Design**: Response bodies MUST NOT nest objects deeper than 3 levels. Use flat structures with references (IDs) for deep relationships. + +**Impact**: Prevents future specs from creating deeply nested APIs that cause client-side parsing issues. + +**Version Bump**: MINOR (new constraint) +``` + +#### Proposed Template Updates + +For each template update: +- **Template**: Which template file +- **Change Type**: Add section | Modify section | Remove section +- **Rationale**: Which specs needed this manually +- **Proposed Diff**: Show before/after + +**Format**: +```markdown +### Template Update 1: Add Performance Considerations to plan-template.md + +**Template**: `.specify/templates/plan-template.md` + +**Change Type**: Add section + +**Rationale**: Specs 016, 017, 018, 019 all added "Performance Considerations" sections manually. This should be a standard plan section. + +**Proposed Diff**: +```diff ++ ## Performance Considerations ++ ++ - Expected load characteristics ++ - Performance targets (latency, throughput) ++ - Bottleneck analysis ++ - Optimization strategy +``` +``` + +#### Proposed Checklist Additions + +For each checklist addition: +- **Checklist**: Which checklist file (or new checklist to create) +- **Items**: New checklist items to add +- **Rationale**: Which specs would have caught issues earlier + +**Format**: +```markdown +### Checklist Addition 1: Rate Limiting Check + +**Checklist**: `.specify/templates/checklist-template.md` (or create `api-checklist-template.md`) + +**Items**: +- [ ] CHK-API-001: Batch operations have rate limiting +- [ ] CHK-API-002: Rate limit errors return 429 with Retry-After header +- [ ] CHK-API-003: Rate limits documented in API contracts + +**Rationale**: Specs 016, 019 both discovered missing rate limiting during implementation. Adding this to default API checklist catches it during planning. +``` + +### 5. Archive Completed Specs (Optional) + +After extracting improvements, optionally archive the analyzed specs: + +Ask user: "Would you like to archive these specs? This will move original files to `specs/.archive/[NNN]-feature-name/` to reduce future token usage." + +If yes: +- Create `specs/.archive/` directory if it doesn't exist +- For each analyzed spec: + - Move entire spec directory to `.archive/` + - Leave a minimal index file at original location (optional) + +**Minimal index format** (if user wants it): +```markdown +# [NNN] - [Feature Name] (Archived) + +Archived: [date] +Location: `specs/.archive/[NNN]-feature-name/` +Constitution updates: [list amendment numbers from retro] +``` + +### 6. User Review and Approval + +Present the complete proposal and ask: + +"Review the proposed improvements above. Which changes would you like to apply?" + +Options: +- [ ] Apply all constitution amendments +- [ ] Apply all template updates +- [ ] Apply all checklist additions +- [ ] Apply selected items (specify which) +- [ ] Save proposal for later review +- [ ] Cancel (no changes) + +### 7. Apply Approved Changes + +For each approved change: + +**Constitution amendments**: +1. Read current `.specify/memory/constitution.md` +2. Apply the amendment +3. Update version number per governance rules +4. Update Sync Impact Report (HTML comment at top) +5. Write updated constitution + +**Template updates**: +1. Read the template file +2. Apply the diff +3. Write updated template + +**Checklist additions**: +1. Read or create the checklist template +2. Add new items with proper CHK-### IDs +3. Write updated checklist + +### 8. Generate Retro Summary + +Output a concise summary: + +```markdown +## Retro Summary + +**Specs Analyzed**: [list with group breakdown if applicable] +**Groups**: [number of groups, or "unified analysis"] +**Patterns Identified**: [count per group if applicable] +**Changes Applied**: +- Constitution: [count] amendments (version [old] → [new]) +- Templates: [count] updates +- Checklists: [count] additions + +**Per-Group Breakdown** (if multi-group analysis): +- Group 1 (Backend & API): [X] amendments, [Y] template updates, [Z] checklist items +- Group 2 (Frontend & UI): [X] amendments, [Y] template updates, [Z] checklist items +- ... + +**Next Steps**: +- New specs will automatically benefit from updated constitution and templates +- Existing in-progress specs may want to incorporate new checklist items +- Consider running retro again after completing next 5-10 specs +``` + +## Operating Principles + +### Context Efficiency + +- **Progressive loading**: Load specs incrementally, not all at once +- **Pattern-focused**: Extract high-signal patterns, not exhaustive documentation +- **Minimal output**: Proposals should be concise and actionable + +### Analysis Guidelines + +- **Evidence-based**: Every proposal must cite specific specs as evidence +- **Cross-spec patterns only**: Don't propose rules based on a single spec (minimum 2-3 specs showing the same pattern) +- **Respect constitution governance**: Follow versioning and amendment rules +- **No speculation**: Only propose constraints actually demonstrated in completed specs +- **Group-focused proposals**: When analyzing multiple groups, ensure proposals are relevant to the group's domain (don't mix daemon constraints with web UI constraints) + +### Safety + +- **User approval required**: Never auto-apply constitution changes +- **Preserve originals**: Archive moves files, doesn't delete them +- **Reversible**: All changes are git-tracked and can be reverted + +## Context + +$ARGUMENTS diff --git a/.specify/extensions/retro/extension.yml b/.specify/extensions/retro/extension.yml new file mode 100644 index 00000000..cf7f6c22 --- /dev/null +++ b/.specify/extensions/retro/extension.yml @@ -0,0 +1,29 @@ +schema_version: "1.0" + +extension: + id: retro + name: Spec Retrospective & Self-Improvement + version: 1.0.2 + description: Analyze completed specs to extract shared constraints and improve constitution, templates, and checklists through self-improvement + author: John + repository: https://github.com/dopejs/speckit-retro-extension + license: MIT + +requires: + speckit_version: ">=0.1.0" + +provides: + commands: + - name: speckit.retro.analyze + file: commands/analyze.md + description: Perform retrospective analysis on completed specs to extract patterns and propose improvements + aliases: + - speckit.retro + +tags: + - retrospective + - self-improvement + - constitution + - quality + - patterns + - governance diff --git a/.specify/memory/constitution.md b/.specify/memory/constitution.md index 9e0ea557..e87660e0 100644 --- a/.specify/memory/constitution.md +++ b/.specify/memory/constitution.md @@ -1,17 +1,17 @@