fraim-framework 2.0.55 → 2.0.56

package/dist/registry/workflows/brainstorming/codebase-brainstorming.md

@@ -0,0 +1,165 @@
+# Workflow: codebase-brainstorming
+
+**Path:** `workflows/brainstorming/codebase-brainstorming.md`
+
+---
+
+# Codebase Brainstorming
+
+## INTENT
+Provide structured approach for analyzing existing codebases and generating improvement suggestions while maintaining accuracy and preventing fabrication of non-existent functionality.
+
+## PRINCIPLES
+- **Evidence-Based Analysis**: Only describe functionality that exists in actual code
+- **Explicit Categorization**: Clearly distinguish between current state and future possibilities
+- **Incremental Thinking**: Build suggestions on existing architecture, not hypothetical systems
+- **Intellectual Honesty**: Better to provide fewer, grounded suggestions than elaborate fabrications
+
+## WORKFLOW
+
+### Phase 1: Codebase Analysis
+**Objective**: Understand the existing system architecture and capabilities
+
+**Actions**:
+1. **Read Core Files**: Identify and read key system files
+2. **Map Architecture**: Understand how components interact
+3. **Identify Patterns**: Look for existing patterns and conventions
+4. **Document Findings**: Create accurate inventory of what exists
+
+**Verification Check**: Can you point to specific files/functions for every claim about existing functionality?
+
+### Phase 2: Categorized Analysis
+**Objective**: Organize findings into clear categories
+
+**Required Categories**:
+
+#### Currently Exists:
+- List only functionality you can point to in actual code
+- Include file paths and specific functions/classes
+- Describe what it actually does (not what it could do)
+
+#### Architectural Patterns:
+- Document existing patterns and conventions
+- Identify design principles already in use
+- Note consistency or inconsistency in current approach
+
+#### Gaps and Opportunities:
+- Areas where functionality is missing
+- Inconsistencies that could be resolved
+- Natural extension points in current architecture
+
+### Phase 3: Grounded Suggestions
+**Objective**: Generate realistic, incremental improvement suggestions
+
+#### Could Be Built (New Functionality):
+- New features that don't exist yet
+- Must build on existing architecture
+- Should follow established patterns
+- Include realistic implementation approach
+
+#### Enhancement to Existing:
+- Modifications to current functionality
+- Extensions of existing patterns
+- Improvements to current implementations
+- Must specify what would change and how
+
+#### Architectural Improvements:
+- Refactoring opportunities
+- Pattern consistency improvements
+- Performance or maintainability enhancements
+
+### Phase 4: Verification and Validation
+**Objective**: Ensure accuracy and prevent fabrication
+
+**Verification Checklist**:
+- [ ] Can I point to actual code for every "Currently Exists" claim?
+- [ ] Did I clearly separate what exists from what could be built?
+- [ ] Are my suggestions grounded in the actual architecture?
+- [ ] Did I avoid presenting hypothetical functionality as real?
+- [ ] Are my enhancement suggestions realistic and incremental?
+
+## RESPONSE TEMPLATE
+
+```markdown
+# Codebase Analysis: [System Name]
+
+## Currently Exists:
+- **[Feature/Component]** (`path/to/file.ext`): [What it actually does]
+- **[Pattern/Convention]** (seen in `file1.ext`, `file2.ext`): [How it works]
+
+## Architectural Patterns:
+- **[Pattern Name]**: [Description and where it's used]
+- **[Design Principle]**: [How it's implemented]
+
+## Could Be Built (New Functionality):
+- **[Proposed Feature]**: [Description, building on existing architecture]
+- **[New Component]**: [How it would integrate with current system]
+
+## Enhancement to Existing:
+- **[Current Feature]** → **[Enhanced Version]**: [Specific improvements]
+- **[Existing Pattern]** → **[Improved Pattern]**: [What would change]
+
+## Implementation Priority:
+1. **High Impact, Low Effort**: [Quick wins]
+2. **High Impact, Medium Effort**: [Valuable improvements]
+3. **Future Considerations**: [Longer-term possibilities]
+```
+
+## ANTI-PATTERNS TO AVOID
+
+### ❌ Fabrication Examples:
+- "You already have a `analyzeSimilarIssues()` function" (when it doesn't exist)
+- "Your retrospectives database" (when it's just files in a folder)
+- Describing elaborate systems that don't exist
+- Presenting hypothetical code as current functionality
+
+### ❌ Vague Suggestions:
+- "Add machine learning" (without specific integration points)
+- "Improve performance" (without identifying bottlenecks)
+- "Make it more scalable" (without understanding current limits)
+
+### ✅ Good Examples:
+- "Currently exists: AI Coach in `src/ai-manager/ai-manager.ts` provides phase-specific instructions"
+- "Could be built: Historical pattern analysis using existing retrospectives in `/retrospectives` folder"
+- "Enhancement to existing: AI Coach could track evidence quality patterns over time by extending the current evidence collection"
+
+## QUALITY GATES
+
+Before completing brainstorming session:
+- [ ] All "Currently Exists" items have file paths
+- [ ] No hypothetical functionality presented as real
+- [ ] Suggestions build incrementally on existing architecture
+- [ ] Clear distinction between current state and future possibilities
+- [ ] Realistic implementation approaches provided
+
+## EXAMPLES
+
+### Good Codebase Analysis:
+```markdown
+## Currently Exists:
+- **Phase-based workflow** (`src/ai-manager/phase-flow.ts`): Manages transitions between implementation phases
+- **AI Coach** (`src/ai-manager/ai-manager.ts`): Provides contextual guidance based on phase and workflow type
+- **Evidence collection** (templates via `get_fraim_file()`): Structured documentation of work completed
+
+## Could Be Built:
+- **Pattern analysis**: Analyze existing retrospectives to identify common failure patterns
+- **Evidence quality scoring**: Evaluate evidence completeness based on historical successful submissions
+```
+
+### Bad Codebase Analysis:
+```markdown
+## Currently Exists:
+- **Smart learning system**: Automatically learns from past issues (doesn't exist)
+- **Advanced pattern matching**: Uses ML to suggest improvements (fabricated)
+- **Retrospectives database**: Queryable database of learnings (it's just markdown files)
+```
+
+## SUMMARY
+
+This workflow ensures brainstorming sessions are:
+- **Accurate**: Grounded in actual codebase reality
+- **Useful**: Provides actionable, incremental suggestions
+- **Honest**: Clearly distinguishes between current and future state
+- **Practical**: Builds on existing architecture and patterns
+
+Remember: Accurate analysis is worth more than elaborate fabrication.