Added and Revised Files to Support SM and DEV Documentation Management Functions
This commit is contained in:
OverlordBaconPants
parent
e753d02a4b
commit
5969fadcee
|
|
@ -16,6 +16,15 @@ persona:
|
|||
style: Extremely concise, pragmatic, detail-oriented, solution-focused
|
||||
identity: Expert who implements stories by reading requirements and executing tasks sequentially with comprehensive testing
|
||||
focus: Executing story tasks with precision, updating Dev Agent Record sections only, maintaining minimal context overhead
|
||||
decision_documentation:
|
||||
responsibility: Document significant technical decisions using lightweight decision log format during implementation
|
||||
focus_areas:
|
||||
- Decisions that will affect future development
|
||||
- Trade-offs between multiple valid approaches
|
||||
- Technical debt creation
|
||||
- Pattern establishment for codebase
|
||||
- Decisions that may surprise or confuse future developers
|
||||
format: Add to story file under "## Technical Decisions" section as decisions are made
|
||||
|
||||
core_principles:
|
||||
- CRITICAL: Story-Centric - Story has ALL info. NEVER load PRD/architecture/other docs files unless explicitly directed in dev notes
|
||||
|
|
@ -23,7 +32,8 @@ core_principles:
|
|||
- CRITICAL: Dev Record Only - ONLY update Dev Agent Record sections (checkboxes/Debug Log/Completion Notes/Change Log)
|
||||
- Sequential Execution - Complete tasks 1-by-1 in order. Mark [x] before next. No skipping
|
||||
- Test-Driven Quality - Write tests alongside code. Task incomplete without passing tests
|
||||
- Debug Log Discipline - Log temp changes to table. Revert after fix. Keep story lean
|
||||
- Debug Log Discipline - Log temp changes to table. Revert after fix. Keep story lean. Meticulously revert all temporary changes before completion
|
||||
- Decision Documentation - Document significant technical decisions in story file as they are made
|
||||
- Block Only When Critical - HALT for: missing approval/ambiguous reqs/3 failures/missing config
|
||||
- Code Excellence - Clean, secure, maintainable code per coding-standards.md
|
||||
- Numbered Options - Always use numbered lists when presenting choices
|
||||
|
|
@ -45,6 +55,8 @@ commands:
|
|||
- "*status" - Show task progress
|
||||
- "*debug-log" - Show debug entries
|
||||
- "*complete-story" - Finalize to "Review"
|
||||
- "*core-dump" - Record story tasks and notes, then run core-dump task
|
||||
- "*document-decision" - Add technical decision to story file
|
||||
- "*exit" - Leave developer mode
|
||||
|
||||
task-execution:
|
||||
|
|
@ -55,16 +67,18 @@ task-execution:
|
|||
- "Debug Log: | Task | File | Change | Reverted? |"
|
||||
- "Completion Notes: Deviations only, <50 words"
|
||||
- "Change Log: Requirement changes only"
|
||||
- "Technical Decisions: Document significant decisions affecting future development"
|
||||
|
||||
blocking: "Unapproved deps | Ambiguous after story check | 3 failures | Missing config"
|
||||
|
||||
done: "Code matches reqs + Tests pass + Follows standards + No lint errors"
|
||||
|
||||
completion: "All [x]→Lint→Tests(100%)→Integration(if noted)→Coverage(80%+)→E2E(if noted)→DoD→Summary→HALT"
|
||||
completion: "All [x]→Lint→Tests(100%)→Integration(if noted)→Coverage(80%+)→E2E(if noted)→DoD→Debug Log Clean→Summary→HALT"
|
||||
|
||||
dependencies:
|
||||
tasks:
|
||||
- execute-checklist
|
||||
- core-dump
|
||||
checklists:
|
||||
- story-dod-checklist
|
||||
```
|
||||
|
|
@ -20,12 +20,22 @@ persona:
|
|||
style: Task-oriented, efficient, precise, focused on clear developer handoffs
|
||||
identity: Story creation expert who prepares detailed, actionable stories for AI developers
|
||||
focus: Creating crystal-clear stories that dumb AI agents can implement without confusion
|
||||
documentation_management:
|
||||
responsibility: Curating and preserving valuable knowledge generated during development while keeping workspace clean and AI context windows efficient
|
||||
includes:
|
||||
- Maintaining /docs/CURATION_NOTES.md (temporary file) during epic development
|
||||
- Extracting lessons learned, technical debt, and key decisions
|
||||
- Updating permanent documentation (/docs/README.md, /docs/TASKS.md, /docs/LESSONS_LEARNED.md, etc.)
|
||||
- Archiving implementation documents after feature completion
|
||||
- Deleting temporary curation notes after extraction
|
||||
- Monitoring technical debt accumulation and recommending paydown sprints using /bmad-agent/templates/tech-debt-prd-tmpl.md
|
||||
core_principles:
|
||||
- Task Adherence - Rigorously follow create-next-story procedures
|
||||
- Checklist-Driven Validation - Apply story-draft-checklist meticulously
|
||||
- Clarity for Developer Handoff - Stories must be immediately actionable
|
||||
- Focus on One Story at a Time - Complete one before starting next
|
||||
- Numbered Options Protocol - Always use numbered lists for selections
|
||||
- Documentation Stewardship - Maintain clean, efficient documentation that preserves valuable knowledge
|
||||
startup:
|
||||
- Greet the user with your name and role, and inform of the *help command.
|
||||
- CRITICAL: Do NOT automatically execute create-next-story tasks during startup
|
||||
|
|
@ -41,13 +51,16 @@ commands:
|
|||
- '*checklist {checklist}" - Show numbered list of checklists, execute selection'
|
||||
- '*doc-shard {PRD|Architecture|Other}" - Execute shard-doc task'
|
||||
- '*index-docs" - Update documentation index in /docs/index.md'
|
||||
- '*curate-docs" - Execute documentation management and curation tasks'
|
||||
- '*exit" - Say goodbye as the Scrum Master, and then abandon inhabiting this persona'
|
||||
dependencies:
|
||||
tasks:
|
||||
- create-next-story
|
||||
- execute-checklist
|
||||
- doc-sharding-task
|
||||
templates:
|
||||
- story-tmpl
|
||||
- tech-debt-prd-tmpl
|
||||
checklists:
|
||||
- story-draft-checklist
|
||||
utils:
|
||||
|
|
|
|||
|
|
@ -57,7 +57,57 @@ The goal is quality delivery, not just checking boxes.]]
|
|||
- [ ] Functionality has been manually verified by the developer (e.g., running the app locally, checking UI, testing API endpoints).
|
||||
- [ ] Edge cases and potential error conditions considered and handled gracefully.
|
||||
|
||||
5. **Story Administration:**
|
||||
5. **Technical Decision Documentation:**
|
||||
|
||||
[[LLM: Document decisions that will affect future development. Focus on significant choices, not obvious ones]]
|
||||
|
||||
- [ ] All significant technical decisions documented in story file under "## Technical Decisions"
|
||||
- [ ] Each decision includes Why, Trade-off, and Debt assessment
|
||||
- [ ] Technical debt items marked with TECH-DEBT comment in code
|
||||
- [ ] Decisions provide enough context for future developers
|
||||
|
||||
**Types of Decisions to Document:**
|
||||
|
||||
**Architecture/Design Patterns**
|
||||
- [ ] Pattern choices (Repository, Factory, Observer, etc.)
|
||||
- [ ] Service communication methods (REST, GraphQL, events)
|
||||
- [ ] Data flow decisions
|
||||
- [ ] Component boundaries and responsibilities
|
||||
|
||||
**Technology/Library Choices**
|
||||
- [ ] External library selections with reasoning
|
||||
- [ ] Framework-specific approaches
|
||||
- [ ] Build tool or bundler decisions
|
||||
- [ ] Database or storage technology choices
|
||||
|
||||
**Performance Trade-offs**
|
||||
- [ ] Caching strategies and TTL decisions
|
||||
- [ ] Database denormalization choices
|
||||
- [ ] Algorithm selection (space vs. time)
|
||||
- [ ] Lazy loading vs. eager loading decisions
|
||||
|
||||
**Security Decisions**
|
||||
- [ ] Authentication/authorization approach
|
||||
- [ ] Data encryption methods
|
||||
- [ ] API security measures
|
||||
- [ ] Secret management strategies
|
||||
|
||||
**Deviation from Standards**
|
||||
- [ ] Any departure from project conventions
|
||||
- [ ] Workarounds for technical limitations
|
||||
- [ ] Temporary solutions that create debt
|
||||
- [ ] Integration compromises with external systems
|
||||
|
||||
**Decision Log Format:**
|
||||
```markdown
|
||||
### [Decision Title]
|
||||
**Decision**: [What was decided]
|
||||
**Why**: [1-2 sentence rationale]
|
||||
**Trade-off**: [What we gave up or compromised]
|
||||
**Debt**: [TECH-DEBT: if applicable, otherwise "None"]
|
||||
```
|
||||
|
||||
6. **Story Administration:**
|
||||
|
||||
[[LLM: Documentation helps the next developer. What should they know?]]
|
||||
|
||||
|
|
@ -65,7 +115,7 @@ The goal is quality delivery, not just checking boxes.]]
|
|||
- [ ] Any clarifications or decisions made during development are documented in the story file or linked appropriately.
|
||||
- [ ] The story wrap up section has been completed with notes of changes or information relevant to the next story or overall project, the agent model that was primarily used during development, and the changelog of any changes is properly updated.
|
||||
|
||||
6. **Dependencies, Build & Configuration:**
|
||||
7. **Dependencies, Build & Configuration:**
|
||||
|
||||
[[LLM: Build issues block everyone. Ensure everything compiles and runs cleanly]]
|
||||
|
||||
|
|
@ -76,7 +126,7 @@ The goal is quality delivery, not just checking boxes.]]
|
|||
- [ ] No known security vulnerabilities introduced by newly added and approved dependencies.
|
||||
- [ ] If new environment variables or configurations were introduced by the story, they are documented and handled securely.
|
||||
|
||||
7. **Documentation (If Applicable):**
|
||||
8. **Documentation (If Applicable):**
|
||||
|
||||
[[LLM: Good documentation prevents future confusion. What needs explaining?]]
|
||||
|
||||
|
|
@ -84,6 +134,17 @@ The goal is quality delivery, not just checking boxes.]]
|
|||
- [ ] User-facing documentation updated, if changes impact users.
|
||||
- [ ] Technical documentation (e.g., READMEs, system diagrams) updated if significant architectural changes were made.
|
||||
|
||||
9. **Curation Handoff:**
|
||||
|
||||
[[LLM: Prepare knowledge for the Scrum Master to preserve valuable insights from this story]]
|
||||
|
||||
- [ ] Technical Decisions section complete in story file
|
||||
- [ ] All TECH-DEBT items marked in code with priority
|
||||
- [ ] Story status updated to "Ready for Curation"
|
||||
- [ ] Notify Scrum Master that story is ready for quick curation
|
||||
- [ ] CURATION_NOTES.md updated with story decisions and lessons learned
|
||||
- [ ] Run `python scripts/check_documentation_status.py` to verify documentation compliance
|
||||
|
||||
## Final Confirmation
|
||||
|
||||
[[LLM: FINAL DOD SUMMARY
|
||||
|
|
|
|||
|
|
@ -142,15 +142,69 @@ Generate a concise validation report:
|
|||
Be pragmatic - perfect documentation doesn't exist. Focus on whether a competent developer can succeed with this story.]]
|
||||
|
||||
| Category | Status | Issues |
|
||||
| ------------------------------------ | ------ | ------ |
|
||||
| 1. Goal & Context Clarity | _TBD_ | |
|
||||
| 2. Technical Implementation Guidance | _TBD_ | |
|
||||
| 3. Reference Effectiveness | _TBD_ | |
|
||||
| 4. Self-Containment Assessment | _TBD_ | |
|
||||
| 5. Testing Guidance | _TBD_ | |
|
||||
| ------------------------------------ | ----------------- | ------ |
|
||||
| 1. Goal & Context Clarity | PASS/FAIL/PARTIAL | |
|
||||
| 2. Technical Implementation Guidance | PASS/FAIL/PARTIAL | |
|
||||
| 3. Reference Effectiveness | PASS/FAIL/PARTIAL | |
|
||||
| 4. Self-Containment Assessment | PASS/FAIL/PARTIAL | |
|
||||
| 5. Testing Guidance | PASS/FAIL/PARTIAL | |
|
||||
|
||||
**Final Assessment:**
|
||||
|
||||
- READY: The story provides sufficient context for implementation
|
||||
- NEEDS REVISION: The story requires updates (see issues)
|
||||
- BLOCKED: External information required (specify what information)
|
||||
|
||||
---
|
||||
|
||||
## DOCUMENTATION CURATION & MANAGEMENT
|
||||
|
||||
### Story-Level Quick Curation (5-10 min per story)
|
||||
- [ ] Review developer's Technical Decisions section in story file
|
||||
- [ ] Extract key items to `/docs/CURATION_NOTES.md` (temporary file):
|
||||
- [ ] Significant technical decisions
|
||||
- [ ] Technical debt items with priority
|
||||
- [ ] Lessons learned (problems & solutions)
|
||||
- [ ] Architectural patterns established
|
||||
- [ ] Flag any critical issues needing immediate attention
|
||||
- [ ] Mark story as "Curation Complete" in story file
|
||||
|
||||
### Epic/Task-Level Full Curation (1-2 hours)
|
||||
- [ ] Review complete `/docs/CURATION_NOTES.md` for the epic
|
||||
- [ ] Identify patterns and themes across stories
|
||||
- [ ] Extract and organize content:
|
||||
- [ ] Technical debt → `/docs/TASKS.md` (with effort estimates)
|
||||
- [ ] Lessons learned → `/docs/LESSONS_LEARNED.md`
|
||||
- [ ] Architectural decisions → Create ADRs for significant ones
|
||||
- [ ] Data structure changes → `/docs/DATA_STRUCTURES.md`
|
||||
- [ ] New features → `/docs/README.md`
|
||||
- [ ] Architecture notes → `/docs/PLANNING.md`
|
||||
- [ ] Check if technical debt threshold reached (≥10 days)
|
||||
- [ ] Prepare curation summary for user
|
||||
|
||||
### User Verification & Archival
|
||||
- [ ] Present curation summary to user:
|
||||
- [ ] Items added to permanent documentation
|
||||
- [ ] Implementation docs to be archived
|
||||
- [ ] Technical debt status
|
||||
- [ ] Get user approval for archival
|
||||
- [ ] Archive implementation documents
|
||||
- [ ] Delete `/docs/CURATION_NOTES.md` (temporary file no longer needed)
|
||||
- [ ] Commit with message: "Archive: [Epic Name] implementation docs"
|
||||
|
||||
## TECHNICAL DEBT MONITORING
|
||||
|
||||
### At Epic/Task Completion
|
||||
- [ ] Review all TECH-DEBT items in `/docs/TASKS.md`
|
||||
- [ ] Estimate effort for accumulated debt (T-shirt sizes: S=1 day, M=3 days, L=1 week)
|
||||
- [ ] Calculate total estimated debt effort
|
||||
- [ ] If total ≥ 10 days, initiate debt paydown process
|
||||
|
||||
### Debt Paydown Process
|
||||
- [ ] Create Technical Debt Analysis document with:
|
||||
- [ ] List of all debt items with effort estimates
|
||||
- [ ] Risk assessment (what could break if not addressed)
|
||||
- [ ] Prioritization recommendation
|
||||
- [ ] Suggested groupings for efficient paydown
|
||||
- [ ] Present to user with recommendation for debt-focused sprint
|
||||
- [ ] If approved, guide user to work with PM on Debt Paydown PRD using `/bmad-agent/templates/tech-debt-prd-tmpl.md`
|
||||
|
|
@ -0,0 +1,90 @@
|
|||
# Technical Debt Paydown PRD
|
||||
|
||||
## Overview
|
||||
This PRD focuses on addressing accumulated technical debt that has reached a threshold requiring dedicated attention. The total estimated effort has exceeded 10 days, triggering the need for a focused debt reduction sprint.
|
||||
|
||||
## Current Debt Status
|
||||
- **Total Items**: [Number]
|
||||
- **Total Estimated Effort**: [Days]
|
||||
- **High Priority Items**: [Number]
|
||||
- **Medium Priority Items**: [Number]
|
||||
- **Low Priority Items**: [Number]
|
||||
|
||||
## Debt Inventory
|
||||
|
||||
| Priority | Description | Effort | Risk | Impact | Story Origin |
|
||||
|----------|-------------|--------|------|--------|--------------|
|
||||
| HIGH | [Description] | [Days] | [Risk description] | [Systems affected] | [Story ref] |
|
||||
| HIGH | [Description] | [Days] | [Risk description] | [Systems affected] | [Story ref] |
|
||||
| MEDIUM | [Description] | [Days] | [Risk description] | [Systems affected] | [Story ref] |
|
||||
| LOW | [Description] | [Days] | [Risk description] | [Systems affected] | [Story ref] |
|
||||
|
||||
## Prioritization Criteria
|
||||
|
||||
1. **High Risk**: Could cause production issues or security vulnerabilities
|
||||
2. **High Friction**: Significantly slows development velocity
|
||||
3. **Quick Wins**: Low effort, high impact improvements
|
||||
4. **Foundation**: Blocks other improvements or feature development
|
||||
|
||||
## Proposed Approach
|
||||
|
||||
### Sprint 1: Critical Items (High Risk & High Friction)
|
||||
- Address all HIGH priority items
|
||||
- Focus on items that pose security or stability risks
|
||||
- Target: [X] days of debt reduction
|
||||
|
||||
### Sprint 2: Foundation & Developer Experience
|
||||
- Address MEDIUM priority items that improve developer velocity
|
||||
- Fix foundational issues blocking other work
|
||||
- Target: [X] days of debt reduction
|
||||
|
||||
### Ongoing: Quick Wins
|
||||
- Incorporate LOW priority items into regular development
|
||||
- Address when working in related code areas
|
||||
- Target: Opportunistic improvement
|
||||
|
||||
## Success Metrics
|
||||
|
||||
- [ ] Reduction in bug reports related to debt areas
|
||||
- [ ] Improved development velocity (measured by story completion rate)
|
||||
- [ ] Reduced time spent on workarounds
|
||||
- [ ] Improved code coverage in affected areas
|
||||
- [ ] Reduced build/deployment times (if applicable)
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Feature development (unless required for debt paydown)
|
||||
- Achieving perfection (aim for "good enough" improvements)
|
||||
- Refactoring areas not identified in debt inventory
|
||||
- Upgrading dependencies not related to identified debt
|
||||
|
||||
## Resource Requirements
|
||||
|
||||
- **Development Team**: [X developers for Y sprints]
|
||||
- **Testing Resources**: [Additional testing needs]
|
||||
- **Code Review**: [Senior developer review requirements]
|
||||
|
||||
## Risk Mitigation
|
||||
|
||||
| Risk | Mitigation Strategy |
|
||||
|------|-------------------|
|
||||
| Introducing new bugs during refactoring | Comprehensive test coverage before changes |
|
||||
| Scope creep during debt paydown | Strict adherence to identified debt items |
|
||||
| Business pressure for features | Clear communication of velocity improvements |
|
||||
|
||||
## Timeline
|
||||
|
||||
- **Start Date**: [Date]
|
||||
- **Sprint 1 Completion**: [Date]
|
||||
- **Sprint 2 Completion**: [Date]
|
||||
- **Final Review**: [Date]
|
||||
|
||||
## Approval
|
||||
|
||||
- [ ] Product Owner
|
||||
- [ ] Technical Lead
|
||||
- [ ] Development Team
|
||||
|
||||
---
|
||||
|
||||
*This PRD was generated based on technical debt accumulated during [Epic/Feature names] development.*
|
||||
|
|
@ -0,0 +1,27 @@
|
|||
# Curation Notes - Active Implementations
|
||||
**Note: This is a temporary file for active work. Completed epics are archived and insights are extracted to LESSONS_LEARNED.md**
|
||||
|
||||
## Active Epics
|
||||
|
||||
### Dashboard Module Separation (Started: 2025-06-14, Completed: 2025-06-15)
|
||||
|
||||
**Epic Summary:**
|
||||
|
||||
|
||||
**Stories Completed:**
|
||||
|
||||
|
||||
**Key Achievements:**
|
||||
|
||||
|
||||
**Technical Impact:**
|
||||
|
||||
---
|
||||
|
||||
## Epic-Level Patterns & Themes
|
||||
|
||||
### Recurring Technical Debt:
|
||||
|
||||
|
||||
### Common Lessons:
|
||||
|
||||
|
|
@ -0,0 +1,39 @@
|
|||
# Lessons Learned
|
||||
|
||||
This document captures key insights, solutions, and learnings from the development process. It serves as a searchable knowledge base for future reference.
|
||||
|
||||
## Format
|
||||
|
||||
Each entry follows this structure:
|
||||
- **Date**: When the lesson was learned
|
||||
- **Context**: Brief description of the situation
|
||||
- **Problem**: What issue was encountered
|
||||
- **Solution**: How it was resolved
|
||||
- **Lesson**: Key takeaway for future projects
|
||||
- **Tags**: Keywords for searchability
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Search Index
|
||||
|
||||
### By Category
|
||||
- **Architecture**: Decisions about system design and patterns
|
||||
- **Performance**: Optimization and scaling lessons
|
||||
- **Security**: Security-related discoveries and solutions
|
||||
- **Integration**: Lessons from third-party integrations
|
||||
- **Testing**: Testing strategies and discoveries
|
||||
- **DevOps**: Deployment and infrastructure insights
|
||||
|
||||
### By Technology
|
||||
- **Frontend**: React, Vue, etc.
|
||||
- **Backend**: Node.js, Python, etc.
|
||||
- **Database**: PostgreSQL, MongoDB, etc.
|
||||
- **Cloud**: AWS, Azure, GCP, etc.
|
||||
|
||||
---
|
||||
|
||||
*Note: This document is maintained by the Scrum Master during documentation curation at the end of each epic/task.*
|
||||
Loading…
Reference in New Issue