Documentation Management

[OverlordBaconPants]

On Discord, I mentioned I'd play around with best practices for document management, content curation. Here goes ... this is my alpha plan, which I'll implement this weekend and see how it performs.

This looks like a lot, but I don't think the role/checklist adjustments I'm making are too heavy, and they'll bring way more value to project curation.

📚 BMAD Documentation Management

🎯 TL;DR

I'm proposing to augment our Scrum Master and Developer AI personas with lightweight documentation curation responsibilities. This helps capture lessons learned, track technical debt, preserve key decisions, and archive completed work - keeping our projects clean and our AI context windows efficient.

🤔 The Problem

As we implement features with our AI personas, we generate tons of documentation: PRDs, epics, stories, implementation plans. Once features are complete, this documentation:

1. Clutters the filesystem - making it harder to navigate
2. Bloats AI context windows - reducing efficiency
3. Hides valuable insights - lessons learned and decisions get buried
4. Lets technical debt accumulate - without visibility or tracking

💡 The Solution

Implement a lightweight documentation curation process that:

• Captures decisions and lessons learned while memory is fresh
• Tracks technical debt with automatic escalation at thresholds
• Archives implementation docs to keep workspaces clean and focused
• Preserves knowledge in searchable, referenceable formats

Key Changes:

• ✍️ Developers document decisions as they code
• 📝 Scrum Masters curate knowledge at Story and Epic/Task completion
• 🗄️ Implementation docs get archived after user confirms Epic/Task completed successfully
• 📊 Technical debt gets tracked with automatic escalation triggers
• 🧠 Lessons learned get preserved for future reference

🔧 Proposed Changes

📝 New Files to Create

# Project Root Level
.ai-ignore                 # Like .gitignore but for AI agents
LESSONS_LEARNED.md         # Searchable repository of insights, perhaps referenced in CLAUDE.MD, .clinerules, etc.
CURATION_NOTES.md          # TEMPORARY notes during development (deleted after curation)

# Archive Structure
/archive/
├── /implementations/       # Archived feature documentation
│   ├── /2024-01-feature-x/
│   └── /2024-02-feature-y/

👨‍💻 Developer Role Augmentation

Add to dev.ide.md:

### Decision Documentation Responsibility

During implementation, document significant technical decisions using the lightweight decision log format. Focus on decisions that:
- Will affect future development
- Involve trade-offs between multiple valid approaches
- Create technical debt
- Establish patterns for the codebase
- May surprise or confuse future developers

Add these to the story file under a "## Technical Decisions" section as you make them.

✅ Developer Checklist Additions

Add to developer checklist:

## During Implementation

### Decision Documentation
- [ ] Document significant technical decisions as they're made
- [ ] Include rationale for trade-offs
- [ ] Note any technical debt incurred
- [ ] Flag decisions that establish patterns

#### 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:

### [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"]

## Story Completion

### Curation Handoff
- [ ] 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

📋 Scrum Master Role Augmentation

Add to sm.ide.md:

### Documentation Management Responsibility

The Scrum Master is responsible for curating and preserving valuable knowledge generated during development while keeping the workspace clean and AI context windows efficient. This includes:

- Maintaining `CURATION_NOTES.md` (temporary file) during epic development
- Extracting lessons learned, technical debt, and key decisions
- Updating permanent documentation (README, TASKS, etc.)
- Archiving implementation documents after feature completion
- Deleting temporary curation notes after extraction
- Monitoring technical debt accumulation and recommending paydown sprints

✅ Scrum Master Checklist Additions

Add new section to Scrum Master checklist:

## Documentation Curation and Management

### Story-Level Quick Curation
- [ ] Review developer's Technical Decisions section in story file
- [ ] Extract key items to `CURATION_NOTES.md` (temporary file):
  - [ ] Significant technical decisions
  - [ ] Technical debt items with priority
  - [ ] Lessons learned (problems and solutions)
  - [ ] Architectural patterns established
- [ ] Flag any critical issues needing immediate attention
- [ ] Mark story as "Curation Complete" in story file

### Epic/Task-Level Full Curation
- [ ] Review complete `CURATION_NOTES.md` for the epic
- [ ] Identify patterns and themes across stories
- [ ] Extract and organize content:
  - [ ] Technical debt → TASKS.md (with effort estimates)
  - [ ] Lessons learned → `LESSONS_LEARNED.md`
  - [ ] Architectural decisions → Create Architecture Decision Records (ADRs) for significant ones
  - [ ] Data structure changes → `DATA_STRUCTURES.md`
  - [ ] New features → `README.md`
  - [ ] Architecture notes → `PLANNING.md`
- [ ] Check if technical debt threshold reached (≥10 days)
- [ ] Prepare curation summary for user

### User Verification and 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 `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 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

📊 Technical Debt Tracking Structure

Update TASKS.md format:

# Technical Debt Registry

## Debt Metrics
- **Total Items**: 15
- **Estimated Effort**: 13 days
- **Last Review**: 2024-01-15
- **Status**: THRESHOLD REACHED - Paydown recommended

## High Priority (Address within 1 sprint)
- [ ] **[5 days]** Refactor authentication to use proper JWT refresh tokens
  - Story: 2.1, Date: 2024-01-10
  - Risk: Security vulnerability
  - Impact: All authenticated endpoints

## Medium Priority (Address within 3 sprints)
- [ ] **[3 days]** Extract hardcoded configuration values
  - Story: 1.3, Date: 2024-01-05
  - Risk: Deployment complexity
  - Impact: DevOps workflows

📁 CURATION_NOTES.md Structure (Temporary File)

# Curation Notes - [Epic/Task Name]
**Note: This is a temporary file that will be deleted after curation**

## Epic: [Epic Name]

### Story 1.1 - [Story Title] - [Date]
**Key Decisions:**
- Chose X over Y because...

**Technical Debt:**
- TECH-DEBT: Hardcoded connection string (High Priority)

**Lessons Learned:**
- API rate limiting issue - solved with exponential backoff

**Architectural Notes:**
- Established pattern for service communication

---

### Story 1.2 - [Story Title] - [Date]
[Same structure...]

🎉 Benefits

1. 🧠 Knowledge Preservation: Lessons learned and decisions are captured and searchable
2. 🧹 Clean Workspace: Implementation docs archived, keeping active workspace focused
3. ⚡ Faster AI Operations: Smaller context windows = more efficient AI agents
4. 💰 Debt Management: Technical debt never spirals out of control
5. 🔍 Better Onboarding: New team members (human or AI) can understand past decisions
6. 📈 Continuous Improvement: Learn from past projects systematically

🤝 Call to Action

This approach has been refined based on software documentation best practices from companies like Spotify, Google, and AWS. It's designed to be lightweight enough for solo developers working with AI agents while comprehensive enough to capture critical knowledge.

What do you think?

• Is the curation overhead reasonable for the value provided?
• Should we adjust the technical debt threshold (currently 10 days)?
• Any other knowledge types we should preserve?
• Does the temporary nature of CURATION_NOTES.md make sense?

Let's discuss and refine this together! 🚀

[bmadcode]

These are some solid ideas!

I would suggest these go to docs instead of root of the project:
LESSONS_LEARNED.md # Searchable repository of insights, perhaps referenced in CLAUDE.MD, .clinerules, etc.
CURATION_NOTES.md # TEMPORARY notes during development (deleted after curation)

the .ai_ignore - different ide's have different ai ignore formats - but I think its good to remind maybe after the installer outputs that people should update their specific ide to ignore certain files from indexing
I think v4a is about as close to stable as it going to be with stuff shuffling around - all agents are now consolidated also - so its a pretty safe time to propose a PR.

One note, I just reduced the amount of content the dev agent is writing to the story files, want to make sure its lean and releated to what the SM needs to know when drafting the next story. trying to avoid the very very long stories that blow up context. But I think your ideas are solid just want to make sure its just succinct critical items that get added

[OverlordBaconPants]

I moved LESSONS_LEARNED.md and CURATION_NOTES.md into the /docs/ directory and changed the roles/checklists to know where to point to these files. Thanks for the suggestions.

Here are the files I now have in my project directory, though I realize these explicit files are likely to be subsumed in your overall revised v4 structure:

• revised /checklists/story-dod-checklist.md
• revised /checklists/story-draft-checklist.md
• revised /personas/dev.ide.md
• revised /personas/sm.ide.md
• new /templates/tech-debt-prd-tmpl.md

Any efforts to make these more clear and compact is greatly appreciated.

I''m currently implementing a PRD for a new feature set using these artifacts, so let's see how it goes.

[OverlordBaconPants]

To make sure this documentation stuff happens at the end of an Epic/Task, I had to modify CLAUDE.md:

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Load bmad-agent/ide-bmad-orchestrator.md and follow the instructions

CRITICAL DOCUMENTATION REMINDERS

During Story Implementation:

1. START of each story: Add an entry to /docs/CURATION_NOTES.md with story ID
2. DURING implementation: Document key decisions and technical debt in CURATION_NOTES.md
3. AFTER completing implementation: Before marking story as done, update CURATION_NOTES.md with:
   • Final decisions made
   • Technical debt incurred
   • Lessons learned
   • Architectural notes

After Epic/Feature Completion:

1. EXTRACT insights from CURATION_NOTES.md to:
   • /docs/LESSONS_LEARNED.md - Add dated entries with tags
   • /docs/README.md - Update if architecture changed
   • /docs/TASKS.md - Add new maintenance tasks
2. ARCHIVE implementation documents to /docs/archive/[epic-name]/
3. DELETE temporary entries from CURATION_NOTES.md

Documentation Checklist Commands:

• Use *checklist sm to see Scrum Master documentation tasks
• Use *doc-status to check documentation compliance
• Use *archive-docs [epic-name] to archive implementation docs

[OverlordBaconPants]

TL;DR - Refined!

I played around with this and made some changes that seem to help.

Files

• Revised:
  • /checklists/story-dod-checklist.md
  • /checklists/story-draft-checklist.md
  • /personas/dev.ide.md
  • /personas/sm.ide.md
• Added:
  • /templates/tech-debt-prd-tmpl.md
  • /docs/CURATION_NOTES.md
  • /docs/LESSONS_LEARNED.md

CLAUDE.md

I found adding this significantly helped keep the SM and Dev roles on track to document stuff at the end of each Story and then curate/archive stuff at the end of each PRD (Epic/Task):

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Load bmad-agent/ide-bmad-orchestrator.md and follow the instructions

## CRITICAL DOCUMENTATION REMINDERS

### During Story Implementation:
1. **START of each story**: Add an entry to `/docs/CURATION_NOTES.md` with story ID
2. **DURING implementation**: Document key decisions and technical debt in CURATION_NOTES.md
3. **AFTER completing implementation**: Before marking story as done, update CURATION_NOTES.md with:
   - Final decisions made
   - Technical debt incurred
   - Lessons learned
   - Architectural notes

### After Epic/Feature Completion:
1. **EXTRACT** insights from CURATION_NOTES.md to:
   - `/docs/LESSONS_LEARNED.md` - Add dated entries with tags
   - `/docs/README.md` - Update if architecture changed
   - `/docs/TASKS.md` - Add new maintenance tasks
2. **ARCHIVE** implementation documents to `/docs/archive/[epic-name]/`
3. **DELETE** temporary entries from CURATION_NOTES.md

### Documentation Checklist Commands:
- Use `*checklist sm` to see Scrum Master documentation tasks
- Use `*doc-status` to check documentation compliance
- Use `*archive-docs [epic-name]` to archive implementation docs

End Results

The one thing I needed to add was another prompt to inform the SM that I vet the PRD as complete, so please proceed to curate and archive documentation.

This looks promising!

And Technical Debt is being captured in my TASKS.md file (which I have stored in my /docs/ directory)

### JavaScript Test Infrastructure
- **Added**: 2025-06-14
- **Priority**: Medium
- **Description**: Complex DOM mocking required for Chart.js tests
- **Impact**: Some tests fail due to mock limitations, not implementation issues
- **Suggested Fix**: Consider using a proper test framework (Jest/Mocha) or integration tests