From 5969fadcee7bd42cd08f55b6e677a41d167de826 Mon Sep 17 00:00:00 2001 From: OverlordBaconPants Date: Sun, 15 Jun 2025 09:39:35 -0400 Subject: [PATCH] Added and Revised Files to Support SM and DEV Documentation Management Functions --- .bmad-core/agents/dev.md | 20 ++- .bmad-core/agents/sm.md | 15 +- .bmad-core/checklists/story-dod-checklist.md | 137 +++++++++++++----- .../checklists/story-draft-checklist.md | 68 ++++++++- .bmad-core/templates/tech-debt-prd-tmpl.md | 90 ++++++++++++ docs/CURATION_NOTES.md | 27 ++++ docs/LESSONS_LEARNED.md | 39 +++++ 7 files changed, 347 insertions(+), 49 deletions(-) create mode 100644 .bmad-core/templates/tech-debt-prd-tmpl.md create mode 100644 docs/CURATION_NOTES.md create mode 100644 docs/LESSONS_LEARNED.md diff --git a/.bmad-core/agents/dev.md b/.bmad-core/agents/dev.md index ac08dc9a..2eec2b05 100644 --- a/.bmad-core/agents/dev.md +++ b/.bmad-core/agents/dev.md @@ -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 -``` +``` \ No newline at end of file diff --git a/.bmad-core/agents/sm.md b/.bmad-core/agents/sm.md index f3be6b54..36b56bbb 100644 --- a/.bmad-core/agents/sm.md +++ b/.bmad-core/agents/sm.md @@ -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,15 +51,18 @@ 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: - template-format -``` +``` \ No newline at end of file diff --git a/.bmad-core/checklists/story-dod-checklist.md b/.bmad-core/checklists/story-dod-checklist.md index 8b20721b..a0faac7f 100644 --- a/.bmad-core/checklists/story-dod-checklist.md +++ b/.bmad-core/checklists/story-dod-checklist.md @@ -24,65 +24,126 @@ The goal is quality delivery, not just checking boxes.]] 1. **Requirements Met:** - [[LLM: Be specific - list each requirement and whether it's complete]] + [[LLM: Be specific - list each requirement and whether it's complete]] - - [ ] All functional requirements specified in the story are implemented. - - [ ] All acceptance criteria defined in the story are met. + - [ ] All functional requirements specified in the story are implemented. + - [ ] All acceptance criteria defined in the story are met. 2. **Coding Standards & Project Structure:** - [[LLM: Code quality matters for maintainability. Check each item carefully]] + [[LLM: Code quality matters for maintainability. Check each item carefully]] - - [ ] All new/modified code strictly adheres to `Operational Guidelines`. - - [ ] All new/modified code aligns with `Project Structure` (file locations, naming, etc.). - - [ ] Adherence to `Tech Stack` for technologies/versions used (if story introduces or modifies tech usage). - - [ ] Adherence to `Api Reference` and `Data Models` (if story involves API or data model changes). - - [ ] Basic security best practices (e.g., input validation, proper error handling, no hardcoded secrets) applied for new/modified code. - - [ ] No new linter errors or warnings introduced. - - [ ] Code is well-commented where necessary (clarifying complex logic, not obvious statements). + - [ ] All new/modified code strictly adheres to `Operational Guidelines`. + - [ ] All new/modified code aligns with `Project Structure` (file locations, naming, etc.). + - [ ] Adherence to `Tech Stack` for technologies/versions used (if story introduces or modifies tech usage). + - [ ] Adherence to `Api Reference` and `Data Models` (if story involves API or data model changes). + - [ ] Basic security best practices (e.g., input validation, proper error handling, no hardcoded secrets) applied for new/modified code. + - [ ] No new linter errors or warnings introduced. + - [ ] Code is well-commented where necessary (clarifying complex logic, not obvious statements). 3. **Testing:** - [[LLM: Testing proves your code works. Be honest about test coverage]] + [[LLM: Testing proves your code works. Be honest about test coverage]] - - [ ] All required unit tests as per the story and `Operational Guidelines` Testing Strategy are implemented. - - [ ] All required integration tests (if applicable) as per the story and `Operational Guidelines` Testing Strategy are implemented. - - [ ] All tests (unit, integration, E2E if applicable) pass successfully. - - [ ] Test coverage meets project standards (if defined). + - [ ] All required unit tests as per the story and `Operational Guidelines` Testing Strategy are implemented. + - [ ] All required integration tests (if applicable) as per the story and `Operational Guidelines` Testing Strategy are implemented. + - [ ] All tests (unit, integration, E2E if applicable) pass successfully. + - [ ] Test coverage meets project standards (if defined). 4. **Functionality & Verification:** - [[LLM: Did you actually run and test your code? Be specific about what you tested]] + [[LLM: Did you actually run and test your code? Be specific about what you tested]] - - [ ] 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. + - [ ] 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: Documentation helps the next developer. What should they know?]] + [[LLM: Document decisions that will affect future development. Focus on significant choices, not obvious ones]] - - [ ] All tasks within the story file are marked as complete. - - [ ] 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. + - [ ] 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 -6. **Dependencies, Build & Configuration:** + **Types of Decisions to Document:** - [[LLM: Build issues block everyone. Ensure everything compiles and runs cleanly]] + **Architecture/Design Patterns** + - [ ] Pattern choices (Repository, Factory, Observer, etc.) + - [ ] Service communication methods (REST, GraphQL, events) + - [ ] Data flow decisions + - [ ] Component boundaries and responsibilities - - [ ] Project builds successfully without errors. - - [ ] Project linting passes - - [ ] Any new dependencies added were either pre-approved in the story requirements OR explicitly approved by the user during development (approval documented in story file). - - [ ] If new dependencies were added, they are recorded in the appropriate project files (e.g., `package.json`, `requirements.txt`) with justification. - - [ ] 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. + **Technology/Library Choices** + - [ ] External library selections with reasoning + - [ ] Framework-specific approaches + - [ ] Build tool or bundler decisions + - [ ] Database or storage technology choices -7. **Documentation (If Applicable):** + **Performance Trade-offs** + - [ ] Caching strategies and TTL decisions + - [ ] Database denormalization choices + - [ ] Algorithm selection (space vs. time) + - [ ] Lazy loading vs. eager loading decisions - [[LLM: Good documentation prevents future confusion. What needs explaining?]] + **Security Decisions** + - [ ] Authentication/authorization approach + - [ ] Data encryption methods + - [ ] API security measures + - [ ] Secret management strategies - - [ ] Relevant inline code documentation (e.g., JSDoc, TSDoc, Python docstrings) for new public APIs or complex logic is complete. - - [ ] User-facing documentation updated, if changes impact users. - - [ ] Technical documentation (e.g., READMEs, system diagrams) updated if significant architectural changes were made. + **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?]] + + - [ ] All tasks within the story file are marked as complete. + - [ ] 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. + +7. **Dependencies, Build & Configuration:** + + [[LLM: Build issues block everyone. Ensure everything compiles and runs cleanly]] + + - [ ] Project builds successfully without errors. + - [ ] Project linting passes + - [ ] Any new dependencies added were either pre-approved in the story requirements OR explicitly approved by the user during development (approval documented in story file). + - [ ] If new dependencies were added, they are recorded in the appropriate project files (e.g., `package.json`, `requirements.txt`) with justification. + - [ ] 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. + +8. **Documentation (If Applicable):** + + [[LLM: Good documentation prevents future confusion. What needs explaining?]] + + - [ ] Relevant inline code documentation (e.g., JSDoc, TSDoc, Python docstrings) for new public APIs or complex logic is complete. + - [ ] 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 @@ -98,4 +159,4 @@ After completing the checklist: Be honest - it's better to flag issues now than have them discovered later.]] -- [ ] I, the Developer Agent, confirm that all applicable items above have been addressed. +- [ ] I, the Developer Agent, confirm that all applicable items above have been addressed. \ No newline at end of file diff --git a/.bmad-core/checklists/story-draft-checklist.md b/.bmad-core/checklists/story-draft-checklist.md index 22954297..465bbd40 100644 --- a/.bmad-core/checklists/story-draft-checklist.md +++ b/.bmad-core/checklists/story-draft-checklist.md @@ -141,16 +141,70 @@ 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_ | | +| Category | Status | Issues | +| ------------------------------------ | ----------------- | ------ | +| 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` \ No newline at end of file diff --git a/.bmad-core/templates/tech-debt-prd-tmpl.md b/.bmad-core/templates/tech-debt-prd-tmpl.md new file mode 100644 index 00000000..18589e76 --- /dev/null +++ b/.bmad-core/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.* \ No newline at end of file diff --git a/docs/CURATION_NOTES.md b/docs/CURATION_NOTES.md new file mode 100644 index 00000000..7b5f00fa --- /dev/null +++ b/docs/CURATION_NOTES.md @@ -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: + diff --git a/docs/LESSONS_LEARNED.md b/docs/LESSONS_LEARNED.md new file mode 100644 index 00000000..dfa3b611 --- /dev/null +++ b/docs/LESSONS_LEARNED.md @@ -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.* \ No newline at end of file