@@ -505,18 +505,37 @@ The following conditions will BLOCK task completion:
505505
506506### **Documentation Discipline**
507507
508- **CRITICAL**: Minimize unnecessary documentation overhead:
508+ **CRITICAL**: Documentation is necessary - but track progress in agile artifacts, not status reports.
509+
510+ **Core Philosophy**:
511+ 1. **Working Code First** - Implementation over meta-documentation
512+ 2. **Agile Artifacts for Progress** - Track work progress in user stories, acceptance criteria, and tasks
513+ 3. **Feature Documentation When Needed** - Document features/concepts in proper locations when they provide value
514+ 4. **No Status Reports** - Don't create "what I did" reports
509515
510516```python
511- # FORBIDDEN: Unsolicited status reports, summaries, or documentation
517+ # FORBIDDEN: Unsolicited status reports about actions taken
512518def complete_feature():
513519 implement_feature()
514- # ❌ DON'T create summary documents unless user asks
520+ update_user_story_status() # ✅ Track progress in agile artifacts
521+ # ❌ DON'T create "what I did" reports
515522 # create_status_report() # FORBIDDEN
516523 # create_summary_document() # FORBIDDEN
517- # create_analysis_document() # FORBIDDEN
524+ # create_bugfix_explanation() # FORBIDDEN
525+ # create_action_report() # FORBIDDEN
526+
527+ # REQUIRED: Create feature/concept documentation when needed
528+ def implement_new_rag_system():
529+ implement_rag_system()
530+ update_user_story() # ✅ Progress in agile artifacts
531+
532+ # ✅ Document the feature/concept in proper location
533+ create_documentation(
534+ path="docs/architecture/rag_system_design.md",
535+ content="RAG system architecture and design decisions"
536+ )
518537
519- # REQUIRED: Only create documentation when explicitly requested
538+ # REQUIRED: Only create status reports when explicitly requested
520539def handle_user_request(request):
521540 if "create summary" in request or "document this" in request:
522541 create_documentation() # ✅ User asked for it
@@ -525,17 +544,41 @@ def handle_user_request(request):
525544```
526545
527546**Rules**:
528- - **No Status Reports**: Don't create status/summary documents unless explicitly requested
529- - **No Analysis Documents**: Don't create analysis files unless user asks
530- - **No Progress Reports**: Don't create progress documentation unless requested
531- - **Just Code**: Focus on implementation, not meta-documentation
532- - **User-Driven**: Only create documentation when user explicitly asks
533-
534- **Exceptions**:
535- - **User Stories/Tasks**: Update acceptance criteria and task status as required
536- - **Code Documentation**: Always document code (docstrings, comments)
537- - **Technical Docs**: Update architecture/design docs when they become stale
538- - **Bug Fixes**: Document in commit messages, not separate files
547+ - **Progress in Agile Artifacts**: Track working progress in user stories/tasks, not separate documents
548+ - **No Status Reports**: Don't create "what I did today" reports unless explicitly requested
549+ - **Feature Documentation**: Create docs for features/concepts when they provide value
550+ - **Right Place, Right Directory**: Put documentation in proper directory structure (docs/architecture/, docs/guides/, etc.)
551+ - **No Action Summaries**: Don't document every step taken
552+ - **Value-Driven**: Only create documentation that provides real value
553+
554+ **What to Always Maintain**:
555+ - ✅ **Agile Artifacts**: Update user stories, tasks, acceptance criteria (progress tracking lives here)
556+ - ✅ **Code Documentation**: Always document code (docstrings, comments, type hints)
557+ - ✅ **Architecture Docs**: Document significant design decisions in `docs/architecture/`
558+ - ✅ **API Documentation**: Keep API references current in `docs/reference/`
559+ - ✅ **User Guides**: Create guides for features in `docs/guides/`
560+
561+ **What NOT to Create (Unless Requested)**:
562+ - ❌ **Bug Fix Reports**: Document in commit messages and code comments, NOT in `docs/fixes/`
563+ - ❌ **Progress Summaries**: Track progress in agile artifacts, not summary documents
564+ - ❌ **Implementation Notes**: Don't create "how I fixed it" documents
565+ - ❌ **Status Reports**: Don't document "what I did" unless user asks
566+ - ❌ **Action Logs**: Don't create logs of actions taken
567+
568+ **When to Create Documentation**:
569+ - ✅ User explicitly requests it
570+ - ✅ New feature/concept needs explanation for team
571+ - ✅ Architecture changes require design documentation
572+ - ✅ API changes need reference updates
573+ - ✅ Complex system needs user guide
574+
575+ **Where to Put Documentation**:
576+ - `docs/architecture/` - System design, patterns, architectural decisions
577+ - `docs/guides/` - User guides, how-tos, tutorials
578+ - `docs/reference/` - API references, technical specifications
579+ - `docs/development/` - Development practices, setup guides
580+ - `docs/agile/` - Agile artifacts (user stories, sprints, backlog)
581+ - **NOT** `docs/fixes/`, `docs/status/`, `docs/reports/`
539582
540583### **TODO List Discipline**
541584
0 commit comments