daffy0208__ai-dev-standards/scripts/brain/DECISION-RULES.md

# Brain Decision Rules

Codified decision logic for the Repository Brain's Layer 3 (Decision Making).

## Workflow Selection Rules

### Rule 1: New Skill Creation

**Triggers**: `new skill`, `add skill`, `create skill`

**Workflow**:

1. Research existing patterns
2. Check if official MCP exists
3. Create SKILL.md
4. Update skill-registry.json
5. Update relationship-mapping.json
6. Update CLAUDE.md
7. Update README.md
8. Validate all changes
9. Commit and push

**Estimated Time**: 2-3 hours

**Required Skills**: `technical-writer`, `quality-auditor`

---

### Rule 2: New Feature Addition

**Triggers**: `new feature`, `add feature`, `implement feature`

**Workflow**:

1. Load project context
2. Check playbooks for patterns
3. Select appropriate skills
4. Implement feature
5. Write tests
6. Update documentation
7. Validate changes
8. Commit

**Estimated Time**: 3-6 hours

**Skill Selection**: Dynamic based on feature type

---

### Rule 3: Enhancement/Improvement

**Triggers**: `enhance`, `improve`, `optimize`, `refactor`

**Workflow**:

1. Load existing implementation
2. Identify gaps
3. Research best practices
4. Implement enhancements
5. Update tests
6. Update documentation
7. Validate
8. Commit

**Estimated Time**: 2-4 hours

**Required Skills**: `quality-auditor`, `performance-optimizer` (if performance), relevant domain skill

---

### Rule 4: Bug Fix

**Triggers**: `fix bug`, `debug`, `resolve issue`

**Workflow**:

1. Reproduce bug
2. Identify root cause
3. Implement fix
4. Write regression test
5. Validate fix
6. Update documentation if needed
7. Commit

**Estimated Time**: 1-3 hours

**Required Skills**: Domain-specific skill, `testing-strategist`

---

### Rule 5: New MCP Creation

**Triggers**: `new mcp`, `add mcp`, `create mcp`

**Workflow**:

1. Research MCP patterns
2. Check official MCPs first
3. Create MCP directory structure
4. Implement MCP server
5. Create integration tests
6. Update mcp-registry.json
7. Update relationship-mapping.json
8. Update CLAUDE.md
9. Validate
10. Commit

**Estimated Time**: 3-5 hours

**Required Skills**: Relevant domain skill, `api-designer`, `testing-strategist`

---

## Skill Selection Rules

### Rule 1: Keyword Matching

**Priority**: High (Score: 10 points)

Match user request keywords against skill **triggers**:

- Exact match: +10 points
- Partial match: +5 points

**Example**:

- Request: "implement authentication"
- Match: `security-engineer` (trigger: "authentication")

---

### Rule 2: Description Matching

**Priority**: Medium (Score: 1-5 points)

Match request words against skill **description**:

- Each matching word: +1 point

**Example**:

- Request: "build REST API"
- Match: `api-designer` (description contains "REST" and "API")

---

### Rule 3: Name Matching

**Priority**: Medium (Score: 5 points)

Match request against skill **name**:

- Name appears in request: +5 points

**Example**:

- Request: "use mvp builder"
- Match: `mvp-builder` (+5 points)

---

### Rule 4: Category Filtering

**Priority**: Low (Optional)

Filter by task category:

- `product-development`: mvp-builder, product-strategist, go-to-market-planner
- `ai-native`: rag-implementer, knowledge-base-manager, multi-agent-architect
- `technical`: frontend-builder, api-designer, security-engineer
- `infrastructure`: deployment-advisor, performance-optimizer
- `ux-design`: ux-designer, visual-designer, accessibility-engineer

---

### Rule 5: Related Skills

**Priority**: Low (Score: 2 points)

If primary skill selected, consider `related_skills`:

- Each related skill: +2 points

**Example**:

- Primary: `rag-implementer`
- Also recommend: `knowledge-base-manager`, `knowledge-graph-builder`

---

## MCP Selection Rules

### Rule 1: Direct Dependency

**Priority**: Critical

For each selected skill, include all `required_mcps` from relationship-mapping.json.

**Example**:

- Skill: `rag-implementer`
- Required MCPs: `vector-database-mcp`, `embedding-generator-mcp`, `semantic-search-mcp`

---

### Rule 2: Transitive Dependency

**Priority**: High

If Skill A requires Skill B, include MCPs from both.

**Example**:

- User selects: `knowledge-base-manager`
- Related: `rag-implementer`
- Include MCPs from both skills

---

### Rule 3: Official MCP Preference

**Priority**: High

Always prefer official MCPs over custom implementations:

- Check MCP registry status: "official" > "community" > "custom"

---

## Pattern Matching Rules

### Rule 1: Architecture Patterns

**Pattern**: RAG System
**Triggers**: "knowledge base", "document search", "semantic search", "Q&A"
**Skills**: `rag-implementer`, `knowledge-base-manager`
**MCPs**: `vector-database-mcp`, `embedding-generator-mcp`

---

**Pattern**: Multi-Agent System
**Triggers**: "agent", "multi-agent", "orchestration", "coordinator"
**Skills**: `multi-agent-architect`, `rag-implementer` (for knowledge)
**MCPs**: `agent-coordinator-mcp`, `vector-database-mcp`

---

**Pattern**: Full-Stack Application
**Triggers**: "web app", "full stack", "frontend and backend"
**Skills**: `frontend-builder`, `api-designer`, `deployment-advisor`
**MCPs**: `component-generator-mcp`, `api-validator-mcp`

---

**Pattern**: MVP Build
**Triggers**: "mvp", "minimum viable", "prototype", "quick build"
**Skills**: `mvp-builder`, `product-strategist`, `frontend-builder`
**MCPs**: `component-generator-mcp`, `feature-prioritizer-mcp`

---

### Rule 2: Technology Stack Patterns

**Stack**: React + Next.js + Supabase
**Skills**: `frontend-builder`, `api-designer`, `security-engineer`
**Integrations**: `supabase`, `openai` (if AI features)

---

**Stack**: AI/ML Application
**Skills**: `rag-implementer`, `multi-agent-architect`, `api-designer`
**Integrations**: `openai`, `anthropic`, `pinecone`

---

## Time Estimation Rules

### Rule 1: Skill Creation

- **Simple skill** (1 pattern): 2 hours
- **Standard skill** (3-5 patterns): 3 hours
- **Complex skill** (7+ patterns): 4-5 hours

---

### Rule 2: MCP Creation

- **Simple MCP** (1-2 tools): 3 hours
- **Standard MCP** (3-5 tools): 4 hours
- **Complex MCP** (integration + tests): 5-6 hours

---

### Rule 3: Feature Implementation

- **UI-only**: 2-3 hours
- **Frontend + Backend**: 4-6 hours
- **Full stack + tests**: 6-8 hours

---

### Rule 4: Enhancement

- **Documentation only**: 1 hour
- **Minor code changes**: 2-3 hours
- **Major refactor**: 4-6 hours

---

## Priority Rules

### Rule 1: Task Priority

**P0 (Critical)**: Foundation, blockers
**P1 (High)**: Core features, user-facing improvements
**P2 (Medium)**: Enhancements, optimizations
**P3 (Low)**: Nice-to-haves, future considerations

---

### Rule 2: Skill Priority

When multiple skills match:

1. **Exact trigger match** (highest priority)
2. **Name match**
3. **Description match**
4. **Related skills** (lowest priority)

---

## Validation Rules

### Rule 1: Registry Consistency

**Check**: All skills in relationship-mapping.json exist in skill-registry.json
**Action**: Error if mismatch

---

### Rule 2: Dependency Completeness

**Check**: All required_mcps exist in mcp-registry.json
**Action**: Warning if missing, suggest creating MCP

---

### Rule 3: Related Skills

**Check**: All related_skills are bidirectional
**Action**: Warning if one-way relationship

---

### Rule 4: Documentation Sync

**Check**: Skill count in CLAUDE.md matches skill-registry.json
**Action**: Error if out of sync

---

## Learning Rules (Future)

### Rule 1: Pattern Extraction

Extract patterns from external repositories:

- Identify recurring architecture patterns
- Score pattern quality
- Add to standards/ if high quality

---

### Rule 2: Skill Discovery

Discover new skill opportunities:

- Find capabilities not covered by existing skills
- Analyze skill usage patterns
- Recommend new skills to create

---

### Rule 3: MCP Optimization

Optimize MCP selection:

- Track which MCPs are used together
- Identify redundant MCPs
- Recommend consolidation

---

## Decision Flow

```
User Request
     ↓
Analyze Keywords
     ↓
Match Workflow Pattern
     ↓
Select Skills (Rule 1-5)
     ↓
Get Required MCPs (Rule 1-3)
     ↓
Estimate Time
     ↓
Generate Recommendation
     ↓
Provide Reasoning
```

---

## Extending Decision Rules

To add new decision rules:

1. **Document the pattern**: What triggers it?
2. **Define the workflow**: What steps are required?
3. **Specify skills**: Which skills are needed?
4. **List dependencies**: What MCPs/tools/integrations?
5. **Estimate time**: How long will it take?
6. **Add to brain-core.ts**: Implement the logic

---

## Version History

**v1.0.0** (2025-10-26): Initial decision rules

- Workflow selection (5 patterns)
- Skill selection (5 rules)
- MCP selection (3 rules)
- Pattern matching (4 patterns)
- Time estimation (4 rules)