codingbuddy-rules 3.0.3 → 3.1.1

package/.ai-rules/CHANGELOG.md

@@ -5,6 +5,34 @@ All notable changes to the Multi-AI Coding Assistant Common Rules System will be
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.1.0] - 2026-01-22
+
+### Added
+
+- **Self-Hosted Plugin Marketplace**
+  - Claude Code plugin marketplace with GitHub Pages deployment
+  - `codingbuddy marketplace add` command for plugin discovery
+  - Automatic GitHub Pages setup in CI workflow
+
+- **SRP Complexity Classifier**
+  - Multi-language support for keyword complexity analysis
+  - Enhanced intent detection for PLAN mode agent selection
+
+### Fixed
+
+- Auto mode detection for PLAN/ACT/EVAL/AUTO keywords in hooks
+- Language configuration now properly respected with diagnostic logging
+- Marketplace add command GitHub repo format handling
+
+### Changed
+
+- **Documentation Improvements**
+  - Multi-language plugin documentation (i18n)
+  - Multi-agent philosophy introduction added to all language versions
+  - Architecture diagram synchronized with current codebase
+
+---
+
 ## [3.0.0] - 2026-01-17
 
 ### Added

package/.ai-rules/rules/core.md

@@ -17,7 +17,7 @@ You have four modes of operation:
 - EVAL mode analyzes ACT results and proposes improved PLAN
 - After EVAL completes, return to PLAN mode with improvement suggestions
 - User can repeat ACT → EVAL → PLAN cycle until satisfied
-- Move to AUTO mode when user types `AUTO` (or localized: 자동, 自動, 自动, AUTOMÁTICO)
+- Move to AUTO mode when user types `AUTO`
 - AUTO mode autonomously cycles through PLAN → ACT → EVAL until quality targets met
 - When in plan mode always output the full updated plan in every response
 
@@ -63,6 +63,81 @@ Create actionable implementation plans following TDD and augmented coding princi
 
 ---
 
+### Structured Reasoning Process (SRP)
+
+**Purpose:**
+Enhance planning quality for complex tasks through systematic thinking with explicit confidence levels.
+
+**Activation:**
+- **COMPLEX tasks**: Full SRP cycle applied automatically
+- **SIMPLE tasks**: Skipped (direct answer)
+- **Auto-classification**: `parse_mode` automatically classifies task complexity
+
+**User Override Flags:**
+- `--srp`: Force SRP even for SIMPLE tasks (e.g., `PLAN --srp fix typo`)
+- `--no-srp`: Skip SRP even for COMPLEX tasks (e.g., `PLAN --no-srp design auth`)
+
+**Classification Criteria:**
+
+| Type | Criteria | Action |
+|------|----------|--------|
+| **SIMPLE** | Single fact, 1 file, no trade-offs, no arch impact | Direct answer |
+| **COMPLEX** | Design decisions, 2+ files, trade-offs, arch impact | Apply SRP |
+
+**The 5-Step Process:**
+
+```
+DECOMPOSE → SOLVE → VERIFY → SYNTHESIZE → REFLECT
+    ↓          ↓        ↓          ↓           ↓
+ Break into  Solve +   Check    Combine    Retry or
+sub-problems confidence quality  results    output
+```
+
+**Confidence Levels (3-Tier System):**
+
+| Level | Range | Criteria |
+|-------|-------|----------|
+| 🟢 High | 0.8+ | Verified facts, official docs, testable |
+| 🟡 Medium | 0.5-0.79 | Reasonable inference, context-dependent |
+| 🔴 Low | <0.5 | Speculation, insufficient info |
+
+**Synthesis Rule:**
+```
+Overall Confidence = min(Sub-problem Confidences)
+```
+
+**REFLECT Safety Limits:**
+- Max retries: 2 (total 3 attempts)
+- After limit: Output with explicit limitations
+- Retry triggers: Overall = 🔴 Low, OR (🟡 Medium AND Critical sub-problem)
+
+**Required Output (COMPLEX tasks only):**
+```markdown
+## 🧠 Structured Reasoning
+
+### Problem Decomposition
+| # | Sub-problem | Confidence |
+|---|-------------|------------|
+| 1 | [Sub-problem] | 🟢/🟡/🔴 |
+
+### Verification
+- ✅ Logic: [Result]
+- ✅ Facts: [Result]
+- ✅ Completeness: [Result]
+- ⚠️ Bias: [Potential bias + mitigation]
+
+### Overall Confidence: 🟢/🟡/🔴
+**Reasoning**: [Based on min() rule]
+
+### ⚠️ Key Caveats
+- [Important limitations or assumptions]
+```
+
+**Reference:**
+See `.ai-rules/rules/structured-reasoning-guide.md` for detailed process and examples.
+
+---
+
 ### Clarification Phase (Optional)
 
 **Purpose:**
@@ -131,6 +206,32 @@ See `.ai-rules/rules/clarification-guide.md` for detailed question guidelines.
 ## 📋 Plan Overview
 [High-level summary of what will be implemented]
 
+## 🧠 Structured Reasoning (COMPLEX tasks only)
+
+### Complexity: COMPLEX/SIMPLE
+[Brief justification for classification]
+
+### Problem Decomposition
+| # | Sub-problem | Confidence |
+|---|-------------|------------|
+| 1 | [Sub-problem 1] | 🟢 High |
+| 2 | [Sub-problem 2] | 🟡 Medium |
+
+### Verification
+- ✅ Logic: [Verification result]
+- ✅ Facts: [Verification result]
+- ✅ Completeness: [Verification result]
+- ⚠️ Bias: [Potential biases and mitigations]
+
+### Overall Confidence: 🟢/🟡/🔴
+**Reasoning**: [Why this level based on min() rule]
+
+### ⚠️ Key Caveats
+- [Important caveat 1]
+- [Important caveat 2]
+
+*Skip this section for SIMPLE tasks*
+
 ## ✅ Todo List
 [Todo list created using todo_write tool - all tasks in pending status]
 
@@ -264,14 +365,24 @@ To preserve this planning session for future reference:
 - Follow framework-specific component patterns as defined in project configuration
 - 🔴 **MUST use `todo_write` tool** to create todo list for all implementation steps
 - All todo items should be in `pending` status when created in PLAN mode
+- 🔴 **MUST apply Structured Reasoning Process (SRP)** for COMPLEX tasks
+- SRP section must include: Problem Decomposition, Verification, Overall Confidence, Key Caveats
+- Confidence levels: 🟢 High (0.8+), 🟡 Medium (0.5-0.79), 🔴 Low (<0.5)
 
 **Verification:**
 - Agent name should appear as `## Agent : [Primary Developer Agent Name]` in response
 - Mode indicator `# Mode: PLAN` should be first line
-- Plan should include structured sections: Plan Overview, Todo List (created with todo_write), Implementation Steps, Planning Specialist sections (when applicable), Risk Assessment, File Structure, Quality Checklist
+- Plan should include structured sections: Plan Overview, Structured Reasoning (COMPLEX only), Todo List (created with todo_write), Implementation Steps, Planning Specialist sections (when applicable), Risk Assessment, File Structure, Quality Checklist
 - Todo list must be created using `todo_write` tool before outputting plan
 - All mandatory checklist items from the Primary Developer Agent should be considered during planning
 - Planning Specialist Agents should be referenced when planning respective areas (Architecture, Test Strategy, Performance, Security, Accessibility, SEO, Design System, Documentation, Code Quality)
+- **SRP Verification (COMPLEX tasks):**
+  - Structured Reasoning section must be present
+  - Problem Decomposition table with confidence levels
+  - Verification checklist (Logic, Facts, Completeness, Bias)
+  - Overall Confidence with reasoning
+  - Key Caveats section
+  - If Overall Confidence = 🔴 Low after 3 attempts, explicit limitations must be stated
 
 ---
 
@@ -459,7 +570,6 @@ To preserve this implementation session for future reference:
 **Trigger:**
 - Type `EVAL` after completing ACT
 - Type `EVALUATE` (also accepted)
-- Korean: `평가해` or `개선안 제시해`
 
 **🔴 Agent Activation (STRICT):**
 - When EVAL is triggered, **Code Reviewer Agent** (`.ai-rules/agents/code-reviewer.json`) **MUST** be automatically activated
@@ -516,7 +626,7 @@ Self-improvement through iterative refinement
 - Evaluate OUTPUT only, not implementer's INTENT
 - No subjective assessments - use objective evidence only
 - Must identify at least 3 improvement areas OR all identified issues
-- Prohibited phrases: See `anti_sycophancy.prohibited_phrases` in `.ai-rules/agents/code-reviewer.json` (English + Korean)
+- Prohibited phrases: See `anti_sycophancy.prohibited_phrases` in `.ai-rules/agents/code-reviewer.json`
 - Start with problems, not praise
 - Challenge every design decision
 
@@ -566,18 +676,18 @@ Self-improvement through iterative refinement
 - [ ] State management: State changes propagate correctly
 - [ ] Async flow: Async/await chains remain valid
 
-## 🔍 리팩토링 검증
+## 🔍 Refactoring Verification
 
-**검토 범위**: [변경된 파일 목록]
+**Review Scope**: [List of changed files]
 
-### 발견된 문제
-- 🔴 `[file.ts:line]` - 조건 분기: [조건문이 특정 케이스만 처리하는 문제]
-- ⚠️ `[file.ts:line]` - 옵셔널 처리: [null/undefined 참조 위험]
+### Issues Found
+- 🔴 `[file.ts:line]` - Conditional branching: [Condition only handles specific cases]
+- ⚠️ `[file.ts:line]` - Optional handling: [null/undefined reference risk]
 
-### 검증 완료 (문제 없음)
-- ✅ [검증 항목명]
+### Verification Complete (No Issues)
+- ✅ [Verification item name]
 
-*스킵 사유: [신규 파일만 생성 / 문서만 변경 / 테스트만 추가 / 해당 없음]*
+*Skip reason: [New files only / Documentation only / Tests only / Not applicable]*
 
 ## 📊 Objective Assessment
 | Criteria | Measured | Target | Status |
@@ -692,7 +802,7 @@ Self-improvement through iterative refinement
 3. [Improvement 3 with location + metric + evidence]
 
 ## 🔍 Anti-Sycophancy Verification
-- [ ] No prohibited phrases used (English: Great job, Well done, Excellent / Korean: 잘했어, 훌륭해, 완벽해, etc.)
+- [ ] No prohibited phrases used (e.g., Great job, Well done, Excellent, Perfect, etc.)
 - [ ] At least 3 improvement areas OR all identified issues reported
 - [ ] All findings include objective evidence (location, metric, target)
 - [ ] Devil's Advocate Analysis completed
@@ -756,10 +866,6 @@ To preserve this evaluation session for future reference:
 
 **Trigger:**
 - Type `AUTO` to start autonomous execution
-- Korean: `자동`
-- Japanese: `自動`
-- Chinese: `自动`
-- Spanish: `AUTOMÁTICO`
 
 **Purpose:**
 Autonomous iterative development - automatically cycling through planning, implementation, and evaluation until quality standards are met.
@@ -770,6 +876,12 @@ Autonomous iterative development - automatically cycling through planning, imple
    - Creates implementation plan following TDD and augmented coding principles
    - Activates Primary Developer Agent automatically
    - Outputs structured plan with todo items
+   - **SRP Integration**: For COMPLEX tasks, applies full Structured Reasoning Process
+     - SRP confidence affects iteration decision
+     - If SRP Overall = 🔴 Low after PLAN, additional analysis may be needed
+     - If Critical sub-problem unresolved, continues to ACT with explicit caveats
+     - EVAL phase considers SRP predictions vs actual outcomes
+     - SRP helps identify root causes when iterations don't converge
 
 2. **Execution Phase: ACT**
    - Executes the plan created in PLAN phase
@@ -830,7 +942,7 @@ Max Iterations: [maxIterations]
 
 Issues Found:
 - Critical: [N]
-- High: [N] <- 반복 필요 (if Critical > 0 OR High > 0)
+- High: [N] <- iteration required (if Critical > 0 OR High > 0)
 - Medium: [N]
 - Low: [N]
 
@@ -860,13 +972,13 @@ Modified Files:
 ---
 # Mode: AUTO - MAX ITERATIONS REACHED
 
-[maxIterations]회 시도했지만 일부 이슈가 남아있습니다.
+After [maxIterations] attempts, some issues remain unresolved.
 
 Remaining Issues:
 - [CRITICAL] [Issue description]
 - [HIGH] [Issue description]
 
-시도한 접근:
+Attempted Approaches:
 - Iteration 1: [approach]
 - Iteration 2: [approach]
 - Iteration 3: [approach]
@@ -948,7 +1060,7 @@ Specialized agents available in `.ai-rules/agents/` directory:
 
 **Code Reviewer** (`.ai-rules/agents/code-reviewer.json`)
 - **Expertise**: Comprehensive code quality evaluation, architecture analysis, performance/security assessment, risk identification
-- **Use when**: 🔴 **STRICT**: When user types `EVAL`, `EVALUATE`, `평가해`, or `개선안 제시해`, this Agent **MUST** be activated automatically
+- **Use when**: 🔴 **STRICT**: When user types `EVAL` or `EVALUATE`, this Agent **MUST** be activated automatically
 - **Key traits**: Evidence-based evaluation (validated through web search), honest about limitations, multi-dimensional analysis, references other rules (no duplication)
 
 **Security Specialist** (`.ai-rules/agents/security-specialist.json`)
@@ -1063,7 +1175,7 @@ Specialized agents available in `.ai-rules/agents/` directory:
 **Code Reviewer** (`@.ai-rules/agents/code-reviewer.json`)
 
 ✅ **Use for (Auto-activated):**
-- 🔴 **STRICT**: When user types `EVAL`, `EVALUATE`, `평가해`, or `개선안 제시해`, this Agent **MUST** be activated automatically
+- 🔴 **STRICT**: When user types `EVAL` or `EVALUATE`, this Agent **MUST** be activated automatically
 - Comprehensive code quality evaluation requests
 - Pre-production quality verification
 - Architecture and design pattern reviews

package/.ai-rules/rules/structured-reasoning-guide.md

@@ -0,0 +1,777 @@
+# Structured Reasoning Process (SRP) Guide
+
+A systematic approach to enhance PLAN mode's planning capabilities through structured thinking.
+
+## Overview
+
+The Structured Reasoning Process (SRP) is a 5-step framework that improves planning quality by:
+- Breaking down complex problems systematically
+- Providing explicit confidence levels for transparency
+- Verifying logic and completeness before output
+- Enabling iterative refinement when needed
+
+**When Applied**: Automatically for COMPLEX tasks, skipped for SIMPLE tasks.
+
+---
+
+## Process Flowchart
+
+```mermaid
+flowchart TD
+    START([Task Received]) --> CLASSIFY{Classify Complexity}
+
+    CLASSIFY -->|SIMPLE| DIRECT[Direct Answer]
+    DIRECT --> OUTPUT_SIMPLE[/"Output: Answer + Confidence + Caveats"/]
+
+    CLASSIFY -->|COMPLEX| DECOMPOSE[1. DECOMPOSE<br/>Break into sub-problems]
+
+    DECOMPOSE --> SOLVE[2. SOLVE<br/>Solve each + assign confidence]
+    SOLVE --> VERIFY[3. VERIFY<br/>Check logic, facts, completeness]
+    VERIFY --> SYNTHESIZE[4. SYNTHESIZE<br/>Combine with min rule]
+    SYNTHESIZE --> REFLECT{5. REFLECT<br/>Meets quality?}
+
+    REFLECT -->|"🟢 High or<br/>🟡 Medium (no critical)"| OUTPUT_COMPLEX[/"Output: Structured Reasoning"/]
+    REFLECT -->|"🔴 Low or<br/>Critical unresolved"| RETRY{Retry count < 2?}
+
+    RETRY -->|Yes| DECOMPOSE
+    RETRY -->|No| OUTPUT_CAVEATS[/"Output with explicit limitations"/]
+
+    OUTPUT_SIMPLE --> END([Complete])
+    OUTPUT_COMPLEX --> END
+    OUTPUT_CAVEATS --> END
+
+    style DECOMPOSE fill:#e1f5fe
+    style SOLVE fill:#e1f5fe
+    style VERIFY fill:#e1f5fe
+    style SYNTHESIZE fill:#e1f5fe
+    style REFLECT fill:#fff3e0
+    style RETRY fill:#ffebee
+```
+
+**Legend:**
+- 🔵 Blue boxes: Core SRP steps
+- 🟠 Orange diamond: Quality decision point
+- 🔴 Red diamond: Retry decision
+
+<details>
+<summary>📄 Text Fallback (for non-Mermaid environments)</summary>
+
+```
+                    ┌─────────────────┐
+                    │  Task Received  │
+                    └────────┬────────┘
+                             │
+                    ┌────────▼────────┐
+                    │    SIMPLE or    │
+                    │    COMPLEX?     │
+                    └────────┬────────┘
+               ┌─────────────┴─────────────┐
+               │                           │
+        ┌──────▼──────┐            ┌───────▼───────┐
+        │   SIMPLE    │            │   COMPLEX     │
+        │   Answer    │            │ 1. DECOMPOSE  │
+        └──────┬──────┘            └───────┬───────┘
+               │                           │
+               │                   ┌───────▼───────┐
+               │                   │   2. SOLVE    │
+               │                   │ + Confidence  │
+               │                   └───────┬───────┘
+               │                           │
+               │                   ┌───────▼───────┐
+               │                   │   3. VERIFY   │
+               │                   └───────┬───────┘
+               │                           │
+               │                   ┌───────▼───────┐
+               │                   │ 4. SYNTHESIZE │
+               │                   │   min() rule  │
+               │                   └───────┬───────┘
+               │                           │
+               │                   ┌───────▼───────┐
+               │                   │  5. REFLECT   │
+               │                   │ Quality OK?   │
+               │                   └───────┬───────┘
+               │                     ┌─────┴─────┐
+               │                     │           │
+               │              ┌──────▼──┐   ┌────▼────┐
+               │              │  🟢/🟡  │   │   🔴    │
+               │              │ Output  │   │ Retry?  │
+               │              └────┬────┘   └────┬────┘
+               │                   │         ┌───┴───┐
+               │                   │         │       │
+               │                   │    ┌────▼───┐ ┌─▼─┐
+               │                   │    │  Yes   │ │No │
+               │                   │    │(<2 try)│ └─┬─┘
+               │                   │    └────┬───┘   │
+               │                   │         │       │
+               │                   │    ┌────▼────┐  │
+               │                   │    │ Return  │  │
+               │                   │    │   to    │  │
+               │                   │    │DECOMPOSE│  │
+               │                   │    └─────────┘  │
+               │                   │                 │
+               │                   │    ┌────────────▼─┐
+               │                   │    │Output with   │
+               │                   │    │limitations   │
+               │                   │    └──────┬───────┘
+               │                   │           │
+               └───────────────────┴───────────┴────────┐
+                                                        │
+                                              ┌─────────▼─────────┐
+                                              │     Complete      │
+                                              └───────────────────┘
+```
+
+</details>
+
+---
+
+## Complexity Classification
+
+Before applying SRP, classify the task:
+
+### SIMPLE Tasks (Skip SRP)
+
+Direct answer without full SRP cycle.
+
+**Criteria:**
+- Single fact verification
+- Definition or syntax questions
+- Clear yes/no questions
+- Single file modification
+- No architectural impact
+- No trade-off analysis needed
+
+**Examples:**
+- "What is the return type of this function?"
+- "How do I declare a readonly property in TypeScript?"
+- "Does this component exist in the codebase?"
+
+### COMPLEX Tasks (Apply SRP)
+
+Full SRP cycle required.
+
+**Criteria:**
+- Design decisions required
+- Multiple factors to analyze
+- Trade-off evaluation needed
+- 2+ files/modules affected
+- Architectural implications
+- Multiple valid approaches exist
+
+**Examples:**
+- "How should we design the authentication system?"
+- "What's the best approach for state management?"
+- "How can we optimize the performance of this feature?"
+
+### Classification Rule
+
+```
+IF (scope <= 1 file) AND (no dependency analysis) AND (no trade-offs)
+  → SIMPLE
+ELSE
+  → COMPLEX
+```
+
+---
+
+## The 5-Step Process
+
+### 1. DECOMPOSE
+
+Break the problem into manageable sub-problems.
+
+**Guidelines:**
+- Identify independent sub-problems
+- Each sub-problem should be answerable
+- Aim for 2-5 sub-problems (not too granular)
+- Consider dependencies between sub-problems
+
+**Output Format:**
+```markdown
+### Problem Decomposition
+| # | Sub-problem | Type | Dependencies |
+|---|-------------|------|--------------|
+| 1 | [Description] | Technical/Design/Risk | None |
+| 2 | [Description] | Technical/Design/Risk | #1 |
+```
+
+---
+
+### 2. SOLVE
+
+Address each sub-problem and assign confidence levels.
+
+**For Each Sub-problem:**
+1. Analyze the specific question
+2. Consider available evidence
+3. Formulate a solution
+4. Assign confidence level
+
+**Confidence Level Assignment:**
+
+| Level | Indicator | Criteria |
+|-------|-----------|----------|
+| 🟢 High | 0.8+ | Official docs, verified facts, testable, matches existing patterns |
+| 🟡 Medium | 0.5-0.79 | Reasonable inference, context-dependent, best practice but not absolute |
+| 🔴 Low | <0.5 | Speculation, insufficient info, multiple valid alternatives |
+
+**Output Format:**
+```markdown
+### Sub-problem Solutions
+| # | Sub-problem | Solution | Confidence | Evidence |
+|---|-------------|----------|------------|----------|
+| 1 | [Question] | [Answer] | 🟢 High | [Source/Reasoning] |
+| 2 | [Question] | [Answer] | 🟡 Medium | [Source/Reasoning] |
+```
+
+---
+
+### 3. VERIFY
+
+Check each solution for quality and correctness.
+
+**Verification Checklist:**
+
+| Aspect | Check | Questions |
+|--------|-------|-----------|
+| **Logic** | ✅/⚠️ | Is the reasoning valid? Any logical fallacies? |
+| **Facts** | ✅/⚠️ | Are stated facts accurate? Can they be verified? |
+| **Completeness** | ✅/⚠️ | Are all aspects covered? Any missing considerations? |
+| **Bias** | ✅/⚠️ | Any assumptions? Alternative perspectives considered? |
+
+**Output Format:**
+```markdown
+### Verification
+- ✅ Logic: [Result and notes]
+- ✅ Facts: [Result and notes]
+- ⚠️ Completeness: [Result and notes - if issues found]
+- ⚠️ Bias: [Potential biases and mitigations]
+```
+
+---
+
+### 4. SYNTHESIZE
+
+Combine sub-problem solutions into a coherent whole.
+
+**Critical vs Non-critical Sub-problems:**
+
+Before combining, classify each sub-problem:
+
+| Type | Criteria | Examples |
+|------|----------|----------|
+| **Critical** | • Directly affects core functionality<br>• Blocking dependency for others<br>• Security/safety implications<br>• Plan cannot proceed without it | Auth method selection, Data model design, API contract definition |
+| **Non-critical** | • Enhancement or optimization<br>• Independent of other sub-problems<br>• No security impact<br>• Plan can proceed with caveats | Performance tuning, UI polish, Documentation |
+
+**Quick Classification Rule:**
+```
+IF sub-problem failure would:
+  - Block implementation entirely → Critical
+  - Cause security vulnerability → Critical
+  - Break other sub-problems → Critical
+  - Only reduce quality/performance → Non-critical
+```
+
+**Combination Rule:**
+```
+Overall Confidence = min(Sub-problem Confidences)
+```
+
+**Rationale:** The overall plan is only as reliable as its weakest component.
+
+**Exception Handling:**
+
+| Scenario | Overall Result |
+|----------|----------------|
+| Any Critical sub-problem = 🔴 Low | 🔴 Low (must REFLECT) |
+| Non-critical = 🔴 Low, Critical = 🟢 High | 🟡 Medium (add caveats) |
+| All = 🟢 High | 🟢 High |
+
+**Output Format:**
+```markdown
+### Synthesis
+**Overall Confidence**: 🟡 Medium
+
+**Reasoning**: Sub-problem #2 has Medium confidence due to [reason],
+which limits overall confidence per min() rule.
+
+**Integration Notes:**
+- [How solutions connect]
+- [Dependencies resolved]
+```
+
+---
+
+### 5. REFLECT
+
+Evaluate if the result meets quality standards.
+
+**Decision Flow:**
+
+```
+IF Overall Confidence = 🔴 Low OR (🟡 Medium AND Critical sub-problem exists)
+  AND retry_count < 2
+THEN
+  → Identify weakness
+  → Retry from DECOMPOSE with refined approach
+ELSE
+  → Output final result with caveats
+```
+
+**Retry Strategies:**
+
+| Retry # | Strategy |
+|---------|----------|
+| 1 | Further decompose weak sub-problems |
+| 2 | Explore alternative approaches |
+| 3+ | Output current result + explicit limitations |
+
+**Output Format (if retrying):**
+```markdown
+### Reflection (Retry Needed)
+**Current Confidence**: 🔴 Low
+**Weak Points**:
+- Sub-problem #2: [Why it's weak]
+**Retry Strategy**: [Approach for next attempt]
+
+---
+[Return to DECOMPOSE with new approach]
+```
+
+**Output Format (if complete):**
+```markdown
+### Reflection (Complete)
+**Final Confidence**: 🟡 Medium
+**Attempts**: 2/3
+**Remaining Uncertainties**:
+- [Uncertainty 1 and why it couldn't be resolved]
+```
+
+---
+
+## Required Output Format
+
+All COMPLEX tasks must include these sections:
+
+```markdown
+## 🧠 Structured Reasoning
+
+### Complexity: COMPLEX
+[Brief justification]
+
+### Problem Decomposition
+| # | Sub-problem | Confidence |
+|---|-------------|------------|
+| 1 | [Sub-problem 1] | 🟢 High |
+| 2 | [Sub-problem 2] | 🟡 Medium |
+
+### Verification
+- ✅ Logic: [Result]
+- ✅ Facts: [Result]
+- ✅ Completeness: [Result]
+- ⚠️ Bias: [Result and mitigation]
+
+### Overall Confidence: 🟡 Medium
+**Reasoning**: [Why this level based on min() rule]
+
+### ⚠️ Key Caveats
+- [Caveat 1 - what user should be aware of]
+- [Caveat 2 - limitations or assumptions]
+```
+
+---
+
+## Examples
+
+### Example 1: SIMPLE Task
+
+**User Request:** "What's the TypeScript syntax for a readonly array?"
+
+**Response:**
+```markdown
+## Answer
+
+Use `readonly` modifier or `ReadonlyArray<T>`:
+
+\`\`\`typescript
+const arr: readonly number[] = [1, 2, 3];
+// or
+const arr: ReadonlyArray<number> = [1, 2, 3];
+\`\`\`
+
+**Confidence**: 🟢 High (TypeScript official documentation)
+**Caveats**: None - this is standard TypeScript syntax.
+```
+
+*Note: SRP skipped - SIMPLE task (single fact, no trade-offs)*
+
+---
+
+### Example 2: COMPLEX Task
+
+**User Request:** "How should we implement user authentication for this app?"
+
+**Response:**
+```markdown
+## 🧠 Structured Reasoning
+
+### Complexity: COMPLEX
+Multiple approaches exist (JWT, session, OAuth), affects multiple modules,
+requires security considerations.
+
+### Problem Decomposition
+| # | Sub-problem | Confidence |
+|---|-------------|------------|
+| 1 | Authentication method selection | 🟡 Medium |
+| 2 | Token storage strategy | 🟢 High |
+| 3 | Session management | 🟢 High |
+| 4 | Security considerations | 🟡 Medium |
+
+### Sub-problem Solutions
+
+**#1 Authentication Method**
+- Solution: JWT with refresh tokens
+- Confidence: 🟡 Medium
+- Evidence: Industry standard, but OAuth might be better for enterprise
+
+**#2 Token Storage**
+- Solution: httpOnly cookies for refresh, memory for access
+- Confidence: 🟢 High
+- Evidence: OWASP recommendations, prevents XSS access to tokens
+
+**#3 Session Management**
+- Solution: Server-side session with Redis
+- Confidence: 🟢 High
+- Evidence: Scalable, supports revocation
+
+**#4 Security**
+- Solution: CSRF protection, rate limiting, secure headers
+- Confidence: 🟡 Medium
+- Evidence: Standard practices, but implementation details vary
+
+### Verification
+- ✅ Logic: Token flow is standard and well-documented
+- ✅ Facts: OWASP guidelines verified
+- ✅ Completeness: Covers auth, storage, session, security
+- ⚠️ Bias: Favoring JWT over sessions - added trade-off discussion
+
+### Overall Confidence: 🟡 Medium
+**Reasoning**: Sub-problems #1 and #4 have Medium confidence,
+limiting overall per min() rule.
+
+### ⚠️ Key Caveats
+- OAuth recommended if enterprise SSO is needed later
+- Security implementation requires detailed review
+- Rate limiting thresholds need tuning based on traffic patterns
+```
+
+---
+
+### Example 3: Boundary Case (2 files but SIMPLE)
+
+**User Request:** "Rename the `getUserData` function to `fetchUserProfile` across the codebase"
+
+**Classification Analysis:**
+- 2+ files affected? Yes (function used in multiple places)
+- Design decisions? No (just renaming)
+- Trade-offs? No
+- Architectural impact? No
+
+**Response:**
+```markdown
+## Complexity: SIMPLE (despite multiple files)
+
+This is a mechanical refactoring task - no design decisions required.
+
+**Action:**
+1. Rename function in `userService.ts`
+2. Update all import sites
+
+**Confidence**: 🟢 High
+**Caveats**: Run tests after rename to verify no missed references.
+```
+
+*Note: File count alone doesn't determine complexity - nature of change matters.*
+
+---
+
+### Example 4: REFLECT Retry Scenario
+
+**User Request:** "Design a caching strategy for our API responses"
+
+**Initial Attempt:**
+```markdown
+## 🧠 Structured Reasoning
+
+### Problem Decomposition
+| # | Sub-problem | Confidence |
+|---|-------------|------------|
+| 1 | Cache location (client/server/CDN) | 🔴 Low |
+| 2 | Cache invalidation strategy | 🔴 Low |
+| 3 | TTL configuration | 🟡 Medium |
+
+### Overall Confidence: 🔴 Low
+**Reasoning**: Critical sub-problems #1 and #2 are Low confidence.
+
+### Reflection (Retry Needed)
+**Weak Points**:
+- #1: Need to know traffic patterns and latency requirements
+- #2: Need to understand data update frequency
+
+**Retry Strategy**: Decompose further - ask about specific use cases
+```
+
+**After Clarification (Retry 1):**
+```markdown
+## 🧠 Structured Reasoning (Attempt 2/3)
+
+### Problem Decomposition (Refined)
+| # | Sub-problem | Confidence |
+|---|-------------|------------|
+| 1a | Client-side cache for static assets | 🟢 High |
+| 1b | Server-side cache for user sessions | 🟢 High |
+| 2a | Time-based invalidation for config | 🟢 High |
+| 2b | Event-based invalidation for user data | 🟡 Medium |
+| 3 | TTL: 5min for API, 1hr for assets | 🟢 High |
+
+### Overall Confidence: 🟡 Medium
+**Reasoning**: All critical sub-problems now High, one non-critical Medium.
+
+### Reflection (Complete)
+**Final Confidence**: 🟡 Medium
+**Attempts**: 2/3
+**Remaining Uncertainty**: Event-based invalidation needs monitoring after deployment.
+```
+
+---
+
+### Example 5: Mixed Complexity Request
+
+**User Request:** "Fix the login button color and redesign the authentication flow"
+
+**Response:**
+```markdown
+## Request Analysis
+
+This request contains two distinct tasks:
+
+| Task | Complexity | Reason |
+|------|------------|--------|
+| Fix login button color | SIMPLE | Single style change, no trade-offs |
+| Redesign auth flow | COMPLEX | Multiple approaches, security implications |
+
+**Recommendation**: Split into two separate tasks.
+
+---
+
+## Task 1: Login Button Color (SIMPLE)
+
+**Action**: Change button color in `LoginButton.tsx`
+**Confidence**: 🟢 High
+**Caveats**: Verify color meets accessibility contrast requirements.
+
+---
+
+## Task 2: Auth Flow Redesign (COMPLEX)
+
+## 🧠 Structured Reasoning
+
+### Problem Decomposition
+| # | Sub-problem | Type | Confidence |
+|---|-------------|------|------------|
+| 1 | Current flow pain points | Analysis | 🟡 Medium |
+| 2 | OAuth vs custom auth | Critical | 🟡 Medium |
+| 3 | Session management | Critical | 🟢 High |
+| 4 | Migration strategy | Non-critical | 🟡 Medium |
+
+[... continues with full SRP ...]
+```
+
+---
+
+## Integration with PLAN Mode
+
+SRP enhances PLAN mode without replacing it:
+
+1. **Clarification Phase** → Gather requirements
+2. **SRP** → Structured analysis (for COMPLEX tasks)
+3. **Plan Output** → Standard PLAN format with SRP section added
+
+The SRP section appears after "Plan Overview" and before "Implementation Steps".
+
+---
+
+## Quick Reference
+
+| Step | Purpose | Key Output |
+|------|---------|------------|
+| DECOMPOSE | Break down problem | Sub-problem table |
+| SOLVE | Address each part | Solutions + Confidence |
+| VERIFY | Check quality | Verification checklist |
+| SYNTHESIZE | Combine results | Overall confidence |
+| REFLECT | Decide next step | Continue or output |
+
+**Confidence Levels:**
+- 🟢 High (0.8+): Verified facts, official sources
+- 🟡 Medium (0.5-0.79): Reasonable but uncertain
+- 🔴 Low (<0.5): Speculation, needs more info
+
+**Safety Limits:**
+- Max retries: 2 (total 3 attempts)
+- After limit: Output with explicit limitations
+
+---
+
+## Interactive Tutorial
+
+### 🎯 Try SRP Yourself
+
+Follow this guided exercise to practice the Structured Reasoning Process.
+
+#### Exercise: "Should we use Redux or Context API for state management?"
+
+**Step 1: Classify Complexity**
+```
+Checklist:
+☐ Single fact? No - requires analysis
+☐ 1 file affected? No - affects architecture
+☐ Trade-offs involved? Yes - performance vs simplicity
+☐ Design decision? Yes
+
+→ Result: COMPLEX ✓
+```
+
+**Step 2: DECOMPOSE**
+```
+Try identifying sub-problems:
+
+Your sub-problems:
+1. ___________________________________
+2. ___________________________________
+3. ___________________________________
+
+Suggested sub-problems:
+1. State complexity (how much state? nested?)
+2. Performance requirements (frequent updates?)
+3. Team familiarity (learning curve?)
+4. Future scalability (will state grow?)
+```
+
+**Step 3: SOLVE with Confidence**
+```
+For each sub-problem, assign:
+🟢 High (0.8+) - You have verified facts
+🟡 Medium (0.5-0.79) - Reasonable inference
+🔴 Low (<0.5) - Speculation
+
+Example:
+| # | Sub-problem | Your Solution | Confidence |
+|---|-------------|---------------|------------|
+| 1 | State complexity | _____________ | 🟢/🟡/🔴 |
+| 2 | Performance | _____________ | 🟢/🟡/🔴 |
+```
+
+**Step 4: VERIFY**
+```
+Check your solutions:
+☐ Logic: Is reasoning valid?
+☐ Facts: Can claims be verified?
+☐ Completeness: Anything missing?
+☐ Bias: Am I favoring one option?
+```
+
+**Step 5: SYNTHESIZE**
+```
+Apply the min() rule:
+Overall = min(all sub-problem confidences)
+
+Your overall confidence: _______
+```
+
+**Step 6: REFLECT**
+```
+Decision tree:
+IF Overall = 🔴 Low → Retry with more research
+IF Overall = 🟡 Medium with Critical unresolved → Retry
+IF Overall = 🟢 High or 🟡 Medium (all critical resolved) → Output
+```
+
+---
+
+### 🧪 Practice Scenarios
+
+**Scenario A: SIMPLE**
+> "What's the syntax for optional chaining in TypeScript?"
+
+Expected: Skip SRP, direct answer with `?.` syntax
+
+---
+
+**Scenario B: COMPLEX**
+> "How should we handle authentication in our Next.js app?"
+
+Expected: Full SRP cycle
+- Sub-problems: Auth method, token storage, session management, security
+- Confidence varies by team context
+- Output includes caveats
+
+---
+
+**Scenario C: Boundary Case**
+> "Rename `fetchData` to `loadData` across 5 files"
+
+Expected: SIMPLE (despite multiple files)
+- Reason: Mechanical change, no design decisions
+
+---
+
+### ⚠️ Common Mistakes to Avoid
+
+Learn from these frequent errors when applying SRP:
+
+| Mistake | Why It's Wrong | Correction |
+|---------|----------------|------------|
+| **Classifying everything as COMPLEX** | Wastes time on trivial tasks | Use the IF rule: 1 file + no trade-offs = SIMPLE |
+| **Skipping VERIFY step** | Leads to flawed conclusions | Always run the 4-point checklist (Logic, Facts, Completeness, Bias) |
+| **Assigning 🟢 High without evidence** | False confidence, bad decisions | Only 🟢 High for verified facts with sources |
+| **Ignoring min() rule in SYNTHESIZE** | Overconfident final assessment | Overall = weakest sub-problem confidence |
+| **Retrying more than 2 times** | Infinite loop, no progress | After 3 attempts, output with explicit limitations |
+| **Treating all sub-problems as Critical** | No prioritization, paralysis | Use the "Would failure block implementation?" test |
+| **Forgetting caveats in output** | User unaware of limitations | Always include ⚠️ Key Caveats section |
+
+**Anti-patterns in Practice:**
+
+```markdown
+❌ Wrong: "Confidence: 🟢 High (I think this is correct)"
+✅ Right: "Confidence: 🟢 High (TypeScript docs, verified in playground)"
+
+❌ Wrong: Overall Confidence: 🟢 High (average of 🟢, 🟡, 🟢)
+✅ Right: Overall Confidence: 🟡 Medium (min of 🟢, 🟡, 🟢 per synthesis rule)
+
+❌ Wrong: Retry attempt 4/3 - trying one more approach
+✅ Right: Attempt 3/3 reached. Output with explicit limitations.
+```
+
+---
+
+### 📝 Self-Assessment Checklist
+
+After completing a PLAN with SRP, verify:
+
+| Check | Done? |
+|-------|-------|
+| Classified SIMPLE vs COMPLEX correctly | ☐ |
+| Sub-problems are independent and answerable | ☐ |
+| Each confidence level has evidence | ☐ |
+| Verification checklist completed | ☐ |
+| Overall confidence follows min() rule | ☐ |
+| Caveats clearly stated | ☐ |
+| Retry limit respected (max 2) | ☐ |
+
+---
+
+## References
+
+- Core workflow: `core.md`
+- TDD practices: `augmented-coding.md`
+- Project context: `project.md`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codingbuddy-rules",
-  "version": "3.0.3",
+  "version": "3.1.1",
   "description": "AI coding rules for consistent practices across AI assistants",
   "main": "index.js",
   "types": "index.d.ts",