zhongwei/gh-ninthspace-claude-code-marketplace-sdd

Files

Zhongwei Li d97a70be33 Initial commit

2025-11-30 08:44:27 +08:00

23 KiB

Raw Permalink Blame History

/sdd:story-complete

Definition

Purpose: Archive a shipped story, capture comprehensive lessons learned, extract reusable components, and update project metrics for continuous improvement.

Syntax: /sdd:story-complete <story_id>

Parameters

Parameter	Type	Required	Default	Description	Validation
story_id	string	Yes	-	Story identifier (e.g., "STORY-2025-001")	Must match pattern STORY-\d{4}-\d{3}

INSTRUCTION: Archive Completed Story

INPUTS

story_id: Story identifier from /docs/stories/completed/
Story file with completion data
Project context from /docs/project-context/

PROCESS

Phase 1: Verification

VERIFY story is in /docs/stories/completed/ directory
IF NOT in completed:
- CHECK /docs/stories/qa/ - suggest running /sdd:story-ship first
- CHECK /docs/stories/review/ - suggest completing QA and shipping
- EXIT with appropriate guidance
READ story file and extract:
- Start date and completion date
- All progress log entries
- Test results and QA outcomes
- Implementation checklist status
- Success criteria completion

Phase 2: Metrics Collection

CALCULATE timeline metrics:
- Total duration (start to completion)
- Time in each stage (development, review, qa)
- Calendar days vs active working days
ANALYZE story progress log to determine:
- Planning time: Initial setup and design
- Implementation time: Active coding
- Testing time: Test writing and debugging
- Review/QA time: Code review and validation
EXTRACT quality metrics:
- Bugs found in review (count from progress log)
- Bugs found in QA (count from progress log)
- Test coverage achieved (from test results)
- Number of commits (from git log)
- Files changed (from git log)
ASSESS business impact:
- Features delivered vs planned
- User-facing improvements
- Performance improvements
- Technical debt addressed

GENERATE metrics summary:

📊 STORY METRICS
════════════════

Timeline:
- Started: [YYYY-MM-DD]
- Completed: [YYYY-MM-DD]
- Total duration: [X] days ([Y] working days)
- Development: [X] days
- Review: [Y] days
- QA: [Z] days

Effort Breakdown:
- Planning: [X] hours
- Implementation: [Y] hours
- Testing: [Z] hours
- Review/QA: [W] hours
- Total: [TOTAL] hours

Quality Metrics:
- Commits: [count]
- Files changed: [count]
- Bugs found in review: [count]
- Bugs found in QA: [count]
- Test coverage: [X%]
- Tests added: [count]

Velocity:
- Story points (if applicable): [points]
- Actual vs estimated: [comparison]

Phase 3: Lessons Learned Capture

PROMPT user for lessons learned (if not in story file):
- What went well?
- What could be improved?
- Any surprises or unexpected challenges?
- Technical insights gained?
- Process improvements identified?
ANALYZE story file for:
- Challenges documented in progress log
- Solutions that worked well
- Technical approaches that succeeded/failed
- Testing strategies effectiveness

COMPILE comprehensive lessons:

📚 LESSONS LEARNED
══════════════════

What Went Well:
- [Success 1: with specific details]
- [Success 2: with specific details]
- [Success 3: with specific details]

What Could Improve:
- [Improvement 1: with action items]
- [Improvement 2: with action items]
- [Improvement 3: with action items]

Surprises & Challenges:
- [Unexpected finding 1]
- [Unexpected finding 2]

Technical Insights:
- [New technique/pattern learned]
- [Library/tool discovery]
- [Architecture decision validated/challenged]

Process Improvements:
- [Workflow enhancement suggestion]
- [Tool/automation opportunity]

For Next Time:
- [ ] [Specific action item 1]
- [ ] [Specific action item 2]
- [ ] [Specific action item 3]

Phase 4: Documentation Updates

IDENTIFY documentation that needs updating:
- README files with new features
- API documentation with new endpoints
- Architecture diagrams with changes
- User guides with new workflows
EXTRACT reusable patterns from implementation:
- Code patterns to standardize
- Configuration templates
- Testing approaches
- Deployment procedures
UPDATE project context if needed:
- Add new tools to /docs/project-context/technical-stack.md
- Document new patterns in /docs/project-context/coding-standards.md
- Update process learnings in /docs/project-context/development-process.md

Phase 5: Reusable Component Extraction

SCAN implementation for reusable code:
- Utility functions to extract
- Components to generalize
- Middleware/helpers to share
- Configuration patterns
IDENTIFY candidates for:
- Shared component library
- Internal utility package
- Starter templates
- Boilerplate generators

DOCUMENT reusable assets:

🔧 REUSABLE COMPONENTS
═════════════════════

Created:
- [Component/utility name]: [path] - [description]
- [Component/utility name]: [path] - [description]

Patterns Documented:
- [Pattern name]: [location] - [use case]

Suggested Extractions:
- [ ] [Code to extract]: [benefit]
- [ ] [Component to generalize]: [benefit]

Phase 6: Story Archival

UPDATE story file with completion data using EXACT STRUCTURE:

APPEND the following sections to the story file in this exact order:

---

## 📊 COMPLETION METRICS

**Archived:** [YYYY-MM-DD HH:MM]
**Total Duration:** [X] calendar days ([Y] working days)
**Status:** Completed and Archived

### Timeline
- **Started:** [YYYY-MM-DD]
- **Completed:** [YYYY-MM-DD]
- **Development:** [X] days
- **Review:** [Y] days
- **QA:** [Z] days

### Effort
- **Planning:** [X] hours
- **Implementation:** [Y] hours
- **Testing:** [Z] hours
- **Review/QA:** [W] hours
- **Total:** [TOTAL] hours

### Quality
- **Commits:** [count]
- **Files Changed:** [count]
- **Tests Added:** [count]
- **Test Coverage:** [X%]
- **Bugs in Review:** [count]
- **Bugs in QA:** [count]

### Velocity
- **Story Points:** [points] (if applicable)
- **Estimated vs Actual:** [comparison]

---

## 📚 RETROSPECTIVE

### What Went Well
- [Specific success 1 with details]
- [Specific success 2 with details]
- [Specific success 3 with details]

### What Could Improve
- [Specific improvement 1 with action]
- [Specific improvement 2 with action]
- [Specific improvement 3 with action]

### Surprises & Challenges
- [Unexpected finding 1]
- [Unexpected finding 2]

### Technical Insights
- [Technical learning 1]
- [Technical learning 2]
- [Technical learning 3]

### Process Improvements
- [Process improvement 1]
- [Process improvement 2]

### Action Items for Next Time
- [ ] [Specific action 1]
- [ ] [Specific action 2]
- [ ] [Specific action 3]

---

## 🔧 REUSABLE COMPONENTS

### Components Created
- **[Component Name]**: `[file path]` - [description]
- **[Component Name]**: `[file path]` - [description]

### Patterns Documented
- **[Pattern Name]**: [location] - [use case]
- **[Pattern Name]**: [location] - [use case]

### Extraction Opportunities
- [ ] **[Code to Extract]**: [benefit]
- [ ] **[Component to Generalize]**: [benefit]

---

## 📈 IMPACT ASSESSMENT

### User Impact
[Description of how this benefits end users]

### Business Impact
[Description of business value delivered]

### Technical Impact
[Description of technical improvements or debt addressed]

### Performance Metrics (if applicable)
- [Metric 1]: [baseline] → [achieved]
- [Metric 2]: [baseline] → [achieved]

---

## 🎯 KEY ACHIEVEMENTS

- [Major achievement 1 with specific deliverable]
- [Major achievement 2 with specific deliverable]
- [Major achievement 3 with specific deliverable]

---

## 🚀 TECHNICAL ADDITIONS

- [New capability/feature 1]
- [New pattern/approach 2]
- [Infrastructure/tooling improvement 3]

---

## 📋 FOLLOW-UP ITEMS

### Technical Debt
- [Technical debt item 1]
- [Technical debt item 2]

### Future Enhancements
- [Enhancement opportunity 1]
- [Enhancement opportunity 2]

### Related Stories
- [Dependency or follow-up story 1]
- [Dependency or follow-up story 2]

---

**Archive Status:** ✅ Complete
**Indexed:** Yes - `/docs/stories/completed/INDEX.md`

NOTES:

ALL sections are REQUIRED (use "N/A" or "None" if section doesn't apply)
Use consistent formatting with exact heading levels shown
Always include separator lines (---) between major sections
Timestamps must use format: YYYY-MM-DD HH:MM
Numbers should include units (days, hours, count, %)
All lists must use consistent bullet format (- or checkbox [ ])

RENAME story file:
- FROM: /docs/stories/completed/[story-id].md
- TO: /docs/stories/completed/[ARCHIVED]-[story-id].md

CREATE OR UPDATE /docs/stories/completed/INDEX.md:

IF FILE DOESN'T EXIST, create with this header:

# Completed Stories Index

A chronological index of all completed and archived stories with key metrics.

## Stories

THEN ADD story entry using this EXACT format:

### [STORY-ID] - [Title]

- **Completed:** [YYYY-MM-DD]
- **Duration:** [X] days ([Y] working days)
- **Test Coverage:** [Z%]
- **Impact:** [one-line business impact summary]
- **File:** [`[ARCHIVED]-[STORY-ID].md`](./%5BARCHIVED%5D-[STORY-ID].md)

NOTES:

Add newest entries at the TOP (reverse chronological order)
Maintain consistent spacing between entries (one blank line)
Use URL-encoded file links for [ARCHIVED] prefix

COMPRESS large artifacts (optional):
- Screenshots folder
- Test recordings
- Large log files

Phase 7: Project Metrics Update

UPDATE project-level metrics:
- Increment completed stories count
- Add to velocity tracking
- Update cycle time averages
- Calculate success rate
CREATE OR UPDATE /docs/project-context/project-metrics.md:
- Total stories completed
- Average cycle time
- Average time per stage
- Quality metrics trends
- Velocity trends
IDENTIFY trends:
- Improving or degrading metrics
- Bottlenecks in process
- Quality improvements
- Velocity patterns

Phase 8: Completion Report

GENERATE comprehensive completion report:

✅ STORY COMPLETION REPORT
══════════════════════════
Story: [STORY-ID] - [Title]
Archived: [YYYY-MM-DD]

SUMMARY:
Successfully delivered [description of implementation] which
[business impact and user value provided].

KEY ACHIEVEMENTS:
• [Achievement 1: specific deliverable]
• [Achievement 2: specific deliverable]
• [Achievement 3: specific deliverable]

TECHNICAL ADDITIONS:
• [New capability/feature added]
• [New pattern/approach implemented]
• [Infrastructure/tooling improvement]

QUALITY METRICS:
• Duration: [X] days ([Y] working days)
• Test coverage: [Z%]
• Bugs found: [review: X, qa: Y]
• Performance: [metrics if applicable]

TEAM LEARNINGS:
• [Key learning 1]
• [Key learning 2]
• [Key learning 3]

REUSABLE ASSETS:
• [Component/utility created]
• [Pattern documented]
• [Template created]

FOLLOW-UP ITEMS:
• [Technical debt to address]
• [Future enhancement opportunity]
• [Process improvement action]

IMPACT:
• Users: [description of user benefit]
• Business: [description of business value]
• Technical: [description of technical improvement]

DISPLAY next steps:

💡 NEXT STEPS:
1. Review follow-up items for backlog
2. Share learnings with team
3. Update related documentation
4. /sdd:project-status to view remaining stories
5. /sdd:story-new to begin next story

OUTPUTS

/docs/stories/completed/[ARCHIVED]-[story-id].md - Archived story with metrics and learnings
/docs/stories/completed/INDEX.md - Updated story index (created or updated)
/docs/project-context/sdd:project-metrics.md - Updated project metrics (created or updated)
Updated documentation files (as needed)
Completion report (displayed to user)

RULES

MUST verify story is in /docs/stories/completed/ before processing
MUST collect comprehensive metrics from story timeline
MUST capture lessons learned (prompt user if not documented)
MUST use EXACT document structure defined in Phase 6 Step 1 (no variation allowed)
MUST include ALL required sections (use "N/A" or "None" if not applicable)
MUST maintain consistent formatting: heading levels, bullet styles, separators
MUST use standard timestamp format: YYYY-MM-DD HH:MM
SHOULD identify reusable components and patterns
SHOULD update project-level metrics
MUST rename file with [ARCHIVED] prefix
MUST create or update /docs/stories/completed/INDEX.md with exact format specified
MUST add newest INDEX entries at TOP in reverse chronological order
ALWAYS generate detailed completion report
SHOULD update project context if new tools/patterns introduced
NEVER delete story files (archive only)
NEVER omit required sections from document structure

Examples

Example 1: Complete Story with Full Metrics

INPUT:
/sdd:story-complete STORY-2025-001

PROCESS:
→ Verifying story location...
→ Found in /docs/stories/completed/STORY-2025-001.md
→ Analyzing story timeline and progress log...
→ Calculating metrics...
→ Extracting lessons learned...
→ Identifying reusable components...

OUTPUT:
✅ STORY COMPLETION REPORT
══════════════════════════
Story: STORY-2025-001 - User Authentication System
Archived: 2025-03-15

SUMMARY:
Successfully delivered a complete user authentication system with
email/password login, registration, password reset, and session
management. This provides secure user access and enables all future
user-specific features.

KEY ACHIEVEMENTS:
• Implemented secure authentication with bcrypt hashing
• Added comprehensive test coverage (95% for auth components)
• Created reusable authentication middleware
• Documented authentication patterns for future features

TECHNICAL ADDITIONS:
• AuthMiddleware for route protection
• SessionManager utility for token handling
• Reusable LoginForm and RegistrationForm components
• Comprehensive authentication test suite

QUALITY METRICS:
• Duration: 12 days (9 working days)
• Test coverage: 95%
• Bugs found: review: 2, qa: 1
• Performance: Login < 200ms, avg 150ms

TEAM LEARNINGS:
• JWT implementation was simpler than session-based auth
• Browser testing caught critical edge cases missed in unit tests
• Early security review prevented potential vulnerabilities
• Test-driven approach significantly reduced bugs in QA

REUSABLE ASSETS:
• AuthMiddleware: app/Middleware/AuthMiddleware.php
• SessionManager: app/Utils/SessionManager.php
• Authentication test helpers: tests/Helpers/AuthHelper.php
• LoginForm component: resources/views/components/LoginForm.blade.php

FOLLOW-UP ITEMS:
• Consider adding OAuth providers (Google, GitHub)
• Implement 2FA in future security story
• Add rate limiting to prevent brute force attacks
• Extract auth utilities to shared package

IMPACT:
• Users: Secure account creation and access to personalized features
• Business: Foundation for user-specific features and data
• Technical: Established authentication pattern for all future features

📊 STORY METRICS
════════════════

Timeline:
- Started: 2025-03-03
- Completed: 2025-03-15
- Total duration: 12 days (9 working days)
- Development: 6 days
- Review: 2 days
- QA: 1 day

Effort Breakdown:
- Planning: 4 hours
- Implementation: 28 hours
- Testing: 12 hours
- Review/QA: 6 hours
- Total: 50 hours

Quality Metrics:
- Commits: 24
- Files changed: 18
- Bugs found in review: 2
- Bugs found in QA: 1
- Test coverage: 95%
- Tests added: 36

📚 LESSONS LEARNED
══════════════════

What Went Well:
- Test-driven development caught edge cases early
- Browser testing revealed UX issues unit tests missed
- Early security review prevented auth vulnerabilities
- Modular design made testing straightforward

What Could Improve:
- Could have started with browser tests earlier
- Initial API design needed refinement during review
- Password reset flow took longer than estimated
- Documentation could have been written alongside code

Surprises & Challenges:
- JWT library had better DX than expected
- Session persistence across subdomains required extra config
- Password reset tokens needed expiration strategy
- Browser autofill behavior required special handling

Technical Insights:
- JWT significantly simpler than session-based auth for SPA
- httpOnly cookies provide better security than localStorage
- Middleware composition pattern works well for auth
- Playwright's auto-wait eliminated flaky tests

Process Improvements:
- Start browser tests earlier in development
- Document API contracts before implementation
- Include security review checklist in story template
- Create reusable test data factories upfront

For Next Time:
- [ ] Write API documentation as first step
- [ ] Create browser test scaffold when starting story
- [ ] Review security checklist during implementation
- [ ] Extract utilities earlier to improve testability

💡 NEXT STEPS:
1. Review follow-up items for backlog
2. Share learnings with team
3. Update authentication documentation
4. /sdd:project-status to view remaining stories
5. /sdd:story-new to begin next story

→ Story archived: /docs/stories/completed/[ARCHIVED]-STORY-2025-001.md
→ Story index updated: /docs/stories/completed/INDEX.md
→ Project metrics updated: /docs/project-context/sdd:project-metrics.md

Example 2: Story Not Ready for Archival

INPUT:
/sdd:story-complete STORY-2025-002

PROCESS:
→ Searching for STORY-2025-002...
→ Found in /docs/stories/qa/

OUTPUT:
❌ Story Not Ready for Completion
═══════════════════════════════

Story: STORY-2025-002 - User Profile Management
Location: /docs/stories/qa/

The story has not been shipped to production yet.

Current Status: qa
Required Status: complete (in /docs/stories/completed/)

NEXT STEPS:
1. /sdd:story-ship STORY-2025-002    # Ship to production
2. /sdd:story-complete STORY-2025-002  # Archive after shipping

Note: Stories must be shipped before archival to ensure
all deployment data and production metrics are captured.

Example 3: Story Missing Lessons Learned

INPUT:
/sdd:story-complete STORY-2025-003

PROCESS:
→ Verifying story location...
→ Found in /docs/stories/completed/STORY-2025-003.md
→ Analyzing story data...
→ Lessons learned section is empty

What went well in this story? (Enter each, then empty line when done)
> Test-driven approach worked great
> Reused authentication patterns from STORY-001
> Performance exceeded expectations
>

What could be improved? (Enter each, then empty line when done)
> Initial design needed iteration
> Could have communicated progress better
>

Any technical insights gained?
> Discovered excellent caching pattern for profile data
> Learned avatar upload optimization techniques
>

→ Capturing lessons learned...
→ Generating completion report...

OUTPUT:
[Full completion report with user-provided lessons learned integrated]

Edge Cases

Story in Wrong Directory

DETECT story not in /docs/stories/completed/
IDENTIFY current location (qa, review, development, backlog)
SUGGEST appropriate next command to progress story
OFFER to force complete if user confirms (with warning)

Missing Metrics Data

DETECT incomplete progress log
CALCULATE what metrics are possible
NOTE missing data in report
SUGGEST improving progress logging for future stories
CONTINUE with available data

Empty Lessons Learned

DETECT empty "Lessons Learned" section
PROMPT user for key learnings interactively
ANALYZE progress log for challenges and solutions
GENERATE lessons from available story data
ENCOURAGE documenting lessons during development

Project Metrics File Doesn't Exist

CREATE /docs/project-context/sdd:project-metrics.md with initial structure
INITIALIZE with current story as first entry
SET baseline metrics
CONTINUE with normal completion

Error Handling

Story ID missing: Return "Error: Story ID required. Usage: /sdd:story-complete <story_id>"
Invalid story ID format: Return "Error: Invalid story ID format. Expected: STORY-YYYY-NNN"
Story not found: Search all directories and report current location
Story not shipped: Suggest completing QA and shipping before archival
File rename error: Log error, keep original name, note in report
Metrics calculation error: Use available data, note gaps in report

Performance Considerations

Parse story file and git log only once
Cache git log results for session
Generate report asynchronously if processing large story
Compress artifacts in background after report generation

/sdd:story-ship - Ship story to production before archival
/sdd:story-metrics - View project-wide metrics and trends
/sdd:project-status - View all project stories and progress
/sdd:story-new - Create next story to work on

Constraints

✅ MUST verify story is shipped before archival
✅ MUST collect comprehensive metrics
✅ MUST capture lessons learned (prompt if missing)
📋 MUST use exact document structure from Phase 6 Step 1 - NO VARIATION
📋 MUST include ALL sections even if content is "N/A" or "None"
📋 MUST maintain consistent heading levels, bullet styles, and separators
📊 MUST create or update /docs/stories/completed/INDEX.md with exact format
📊 MUST add newest INDEX entries at TOP (reverse chronological)
📊 SHOULD update project-level metrics
🔧 SHOULD identify reusable components
📝 MUST generate detailed completion report
💾 MUST rename file with [ARCHIVED] prefix
🚫 NEVER delete story files
🚫 NEVER omit required sections
⏱️ MUST use standard timestamp format: YYYY-MM-DD HH:MM

23 KiB Raw Permalink Blame History