wogiflow 1.4.5 → 1.4.7

package/.claude/commands/wogi-decide.md

@@ -0,0 +1,193 @@
+Interactive rule creation with clarifying questions. Invoke when user says "from now on...", "let's make it a rule", "always do X", "never do Y", or "standardize on...".
+
+## Usage
+
+```bash
+/wogi-decide "from now on, always use error boundaries in React components"
+/wogi-decide "the convention should be kebab-case for all config files"
+/wogi-decide                # Interactive mode — asks what rule to create
+```
+
+## Trigger Phrases
+
+Auto-routed from `/wogi-start` when user says:
+- "from now on..."
+- "let's make it a rule..."
+- "always do X" / "never do Y"
+- "the convention should be..."
+- "we should standardize on..."
+- "update our rules to..."
+- "add a rule for..."
+
+## How It Works
+
+### Step 1: Parse the Rule Intent
+
+Extract from the user's input:
+- **What**: The rule statement (what to do or not do)
+- **Scope hint**: Any mentioned scope (all files? specific types? specific feature?)
+- **Strength**: Mandatory ("always", "never", "must") vs advisory ("prefer", "try to", "when possible")
+
+### Step 2: Check for Duplicate Rules
+
+**BEFORE asking clarifying questions**, check for existing similar rules:
+
+1. Read `.workflow/state/decisions.md`
+2. Search for keywords from the proposed rule
+3. If a similar rule exists (same topic, same intent):
+
+```
+A similar rule already exists:
+
+> [Existing rule statement from decisions.md]
+(Added: [date], Section: [section])
+
+Options:
+1. Update the existing rule (modify scope, wording, or exceptions)
+2. Create a new separate rule (if genuinely different)
+3. Cancel (rule already covered)
+```
+
+Use `AskUserQuestion` to present these options.
+
+### Step 3: Assess Clarity
+
+Evaluate if the rule needs clarification. **Skip questions if the rule is already clear and specific.**
+
+A rule is clear when it has:
+- Specific action (what to do)
+- Obvious scope (when it applies)
+- No ambiguity in interpretation
+
+**Examples of clear rules (skip to Step 4):**
+- "Catch blocks must use `err` not `e`" — Clear action, obvious scope
+- "All file names must be kebab-case" — Clear action, universal scope
+- "Never commit .env files" — Clear prohibition, obvious scope
+
+**Examples of ambiguous rules (ask questions):**
+- "Always use error boundaries" — Which components? All? Only pages?
+- "We should validate inputs" — Which inputs? Client-side? Server-side? Both?
+- "Use TypeScript strict mode" — New files only? Existing files too?
+
+### Step 4: Ask Clarifying Questions (if needed)
+
+Only ask questions that are genuinely needed. Use `AskUserQuestion` with up to 4 questions:
+
+**Possible questions (ask only what's ambiguous):**
+
+1. **Scope**: "When does this apply?"
+   - All files / specific file types / specific feature areas / new code only
+2. **Exceptions**: "Are there cases where this should NOT apply?"
+   - Yes (describe) / No exceptions / Not sure yet
+3. **Verification**: "How should we check compliance?"
+   - Code review / Lint rule / Manual check / Automated test
+4. **Rationale** (only if not obvious): "Why is this important?"
+   - Helps future developers understand the rule
+
+**Do NOT ask all 4 questions every time.** For most rules, 0-2 questions suffice.
+
+### Step 5: Write the Rule to decisions.md
+
+**Input sanitization**: Before writing, enforce these guards on user-supplied rule text:
+- Maximum 500 characters for the rule statement
+- Strip markdown structural characters (`---`, `##`, HTML comments `<!-- -->`) from user-supplied text
+- Escape any markdown headings within the rule body (prefix with `\`)
+- This prevents accidental or malicious structural alteration of decisions.md
+
+Read `.workflow/state/decisions.md` and add the rule to the appropriate section.
+
+**Section mapping:**
+- Code style / naming → "Coding Standards"
+- Component / UI patterns → "Component Architecture"
+- Security practices → "Coding Standards > Security Patterns"
+- Architecture / design → "Architecture Decisions"
+- File / folder organization → "File/Folder Structure"
+- Process / workflow → "Operational Procedures"
+- Review / cleanup → "Review & Cleanup Procedures"
+
+**Rule format:**
+
+```markdown
+### [Rule Title] (YYYY-MM-DD)
+**Source**: user-decision
+**Scope**: [when this applies]
+> [Clear, actionable rule statement]
+
+**Rationale**: [why this rule exists]
+**Exceptions**: [when this does NOT apply, or "None"]
+**Verification**: [how to check compliance]
+```
+
+### Step 6: Check for Existing Code Violations (Optional)
+
+After writing the rule, optionally scan for existing violations:
+
+1. Use Grep to search for patterns that violate the new rule
+2. If violations found (N > 0):
+
+```
+Found N existing violations of this new rule.
+
+Options:
+1. Create a fix task for existing violations
+2. Apply rule to new code only (grandfather existing)
+3. Fix them right now (if small count)
+```
+
+Use `AskUserQuestion` to present options.
+
+If user chooses option 1:
+- **Require explicit user confirmation** before writing to ready.json (display violation count and file list first)
+- Cap display at 50 violations — if more exist, warn user about scope
+- Create a task in `ready.json` backlog: "Fix N violations of [rule name]"
+
+### Step 7: Update Request Log
+
+Add entry to `.workflow/state/request-log.md`:
+
+```markdown
+### R-[NNN] | [YYYY-MM-DD HH:MM]
+**Type**: new
+**Tags**: #rule #decisions
+**Request**: "Create rule: [rule title]"
+**Result**: Added rule to decisions.md ([section])
+**Files**: `.workflow/state/decisions.md`[, `.workflow/state/ready.json` if fix task created]
+```
+
+### Step 8: Confirm
+
+```
+Rule created: "[Rule Title]"
+Section: [section in decisions.md]
+Scope: [scope]
+
+This rule will be enforced in future code reviews and task execution.
+```
+
+## Options
+
+- `--quick` — Skip clarifying questions, write rule directly from input
+- `--from-pattern` — Create rule from a pattern in feedback-patterns.md (used by /wogi-learn)
+
+## Configuration
+
+In `config.json`:
+```json
+{
+  "decide": {
+    "requireRationale": true,
+    "scanForViolations": true,
+    "maxClarifyingQuestions": 4
+  }
+}
+```
+
+## Files
+
+| Action | File |
+|--------|------|
+| Read (duplicate check) | `.workflow/state/decisions.md` |
+| Write (new rule) | `.workflow/state/decisions.md` |
+| Read (violation scan) | Codebase files via Grep |
+| Write (log) | `.workflow/state/request-log.md` |
+| Write (fix task) | `.workflow/state/ready.json` (if violations found) |

package/.claude/commands/wogi-help.md

@@ -57,6 +57,13 @@ DEBUGGING
 /wogi-debug-hypothesis [desc] Parallel hypothesis investigation
 /wogi-trace [feature]        Code flow trace for a feature
 
+═══════════════════════════════════════════════════════════════
+LEARNING & RULES
+═══════════════════════════════════════════════════════════════
+/wogi-decide [rule]      Create project rule with clarifying questions
+/wogi-learn              Promote feedback patterns to decision rules
+/wogi-retrospective      Guided session reflection with lesson capture
+
 ═══════════════════════════════════════════════════════════════
 SEARCH & CONTEXT
 ═══════════════════════════════════════════════════════════════

package/.claude/commands/wogi-learn.md

@@ -0,0 +1,242 @@
+Interactive pattern promotion from feedback to decisions. Invoke when user says "let's learn from this", "we keep making this mistake", "promote this pattern", or "what have we learned?".
+
+## Usage
+
+```bash
+/wogi-learn                    # Show all patterns, select to promote
+/wogi-learn --all              # Bulk promote all qualifying patterns (count >= 3)
+/wogi-learn "learn from what just happened"  # Learn from recent incident
+```
+
+## Trigger Phrases
+
+Auto-routed from `/wogi-start` when user says:
+- "let's learn from this"
+- "we keep making this mistake"
+- "promote this pattern"
+- "what have we learned?"
+- "extract lessons"
+- "capture this learning"
+
+## How It Works
+
+### Step 1: Load Pattern Data
+
+Read these files:
+1. `.workflow/state/feedback-patterns.md` — Accumulated patterns with counts
+2. `.workflow/state/decisions.md` — Existing rules (to check for duplicates)
+3. `.workflow/corrections/*.md` — Recent correction reports with lessons (sorted by mtime; if directory doesn't exist or is empty, skip)
+
+### Step 2: Choose Mode
+
+**Mode A: Browse patterns** (default — no argument)
+**Mode B: Learn from incident** (argument provided, e.g., "learn from what just happened")
+**Mode C: Bulk promotion** (`--all` flag)
+
+---
+
+### Mode A: Browse Patterns
+
+1. Parse `feedback-patterns.md` for all patterns in the "Pending Patterns" and "Patterns Log" sections
+2. Sort by occurrence count (highest first)
+3. Display:
+
+```
+Accumulated Patterns (N total):
+
+Ready to Promote (count >= 3):
+  1. [try-catch-file-reads] (4 occurrences) — File reads need try-catch
+  2. [review-similar-code] (4 occurrences) — Check similar code when fixing bugs
+
+Approaching Threshold (count 2):
+  3. [use-safeJsonParse] (2 occurrences) — Use safeJsonParse instead of JSON.parse
+  4. [extract-duplicate-logic] (2 occurrences) — Extract shared logic
+
+Monitoring (count 1):
+  5. [validate-shell-params] (1 occurrence) — Validate shell parameters
+  ... (N more)
+
+Which pattern would you like to promote? (Enter number, or "skip")
+```
+
+Use `AskUserQuestion` to let user select.
+
+4. When user selects a pattern, go to **Step 3: Promote Pattern**.
+
+### Mode B: Learn from Incident
+
+1. Read `.workflow/state/request-log.md` — last 5 entries
+2. Read recent files in `.workflow/corrections/*.md` (last 3 by modification time; if directory doesn't exist or is empty, analyze request-log only and note: "No correction reports found — analyzing request-log entries.")
+3. Analyze what went wrong:
+   - What was the task?
+   - What failure occurred?
+   - What was the root cause?
+   - What should have been done differently?
+
+4. Propose a rule:
+
+```
+Based on recent work, here's what I found:
+
+Incident: [description from request-log/corrections]
+Root Cause: [analysis]
+Proposed Rule: "[rule statement]"
+
+Should I create this as a project rule?
+1. Yes, create the rule (routes to /wogi-decide flow)
+2. Add to feedback-patterns for monitoring first
+3. Skip — not a recurring issue
+```
+
+Use `AskUserQuestion` to present options.
+
+If option 1: Invoke `/wogi-decide --from-pattern` with the proposed rule (uses streamlined path). If user cancels within the /wogi-decide sub-flow, return to wogi-learn and display "Rule creation cancelled. Pattern not promoted."
+If option 2: Add to `feedback-patterns.md` Pending Patterns section with count 1.
+
+### Mode C: Bulk Promotion
+
+1. Parse `feedback-patterns.md` for patterns with count >= 3
+2. For each qualifying pattern, display:
+
+```
+Bulk Promotion: N patterns qualify (count >= 3)
+
+1. [try-catch-file-reads] (4x) — Promote? [Y/n]
+   → Proposed rule: "Always wrap fs.readFileSync in try-catch"
+
+2. [review-similar-code] (4x) — Promote? [Y/n]
+   → Proposed rule: "When fixing a bug, search for similar patterns elsewhere"
+
+Approve all? Or review individually?
+```
+
+Use `AskUserQuestion`:
+- "Approve all" — Promote all qualifying patterns
+- "Review individually" — Go through each one
+
+For each approved pattern, run **Step 3: Promote Pattern**.
+
+---
+
+### Step 3: Promote a Pattern
+
+Given a pattern to promote:
+
+1. **Extract rule from pattern:**
+   - Pattern description → Rule statement
+   - Pattern count → Evidence for rationale
+   - Correction examples → Verification criteria
+
+2. **Delegate duplicate checking to `/wogi-decide --from-pattern`** which handles duplicate detection and the full rule-writing flow. This ensures a single source of truth for all rule-creation logic.
+
+3. **Ask user for any additions:**
+
+```
+Promoting pattern: [pattern-name]
+
+Proposed rule:
+> [Rule statement derived from pattern]
+
+Rationale: Occurred [N] times. [Brief description of why this matters]
+Scope: [Inferred scope from pattern data]
+
+Anything to add or change?
+- Additional scope or exceptions?
+- Specific verification steps?
+
+(Press enter to accept as-is, or type modifications)
+```
+
+4. **Write to decisions.md:**
+   Use the same format as `/wogi-decide`:
+
+```markdown
+### [Rule Title] (YYYY-MM-DD)
+**Source**: promoted-pattern ([N] occurrences in feedback-patterns.md)
+**Scope**: [scope]
+> [Rule statement]
+
+**Rationale**: Pattern occurred [N] times. [description]
+**Exceptions**: [exceptions or "None"]
+**Verification**: [how to check]
+```
+
+5. **Mark as promoted in feedback-patterns.md:**
+   Update the pattern's row:
+   - Set "Promoted To" column to `decisions.md`
+   - Set "Status" column to `PROMOTED`
+   - Or move to "Promotion History" section
+
+### Step 4: Update Request Log
+
+```markdown
+### R-[NNN] | [YYYY-MM-DD HH:MM]
+**Type**: change
+**Tags**: #learning #decisions #pattern-promotion
+**Request**: "Promote pattern: [pattern-name]"
+**Result**: Pattern promoted to decisions.md ([section]). [N] patterns reviewed.
+**Files**: `.workflow/state/decisions.md`, `.workflow/state/feedback-patterns.md`
+```
+
+### Step 5: Summary
+
+```
+Learning Summary:
+- Patterns reviewed: N
+- Patterns promoted: M
+- New rules added to decisions.md: M
+
+These rules will be enforced in future code reviews and task execution.
+```
+
+## Edge Cases
+
+### No patterns to promote
+```
+No patterns to promote.
+
+Patterns are recorded during:
+- Code reviews (/wogi-review)
+- Corrections (/wogi-correction)
+- Standards compliance checks
+
+As patterns accumulate (count >= 3), they become eligible for promotion.
+```
+
+### All patterns already promoted
+```
+All qualifying patterns have already been promoted to decisions.md.
+
+Monitoring [N] patterns with count < 3. They'll become eligible as occurrences increase.
+```
+
+## Options
+
+- `--all` — Bulk promote all patterns with count >= threshold
+- `--threshold N` — Override promotion threshold (default: 3, minimum: 2). Values below 2 are rejected to prevent noise promotion.
+- `--quick` — Skip individual confirmation prompts, but still display count and require final confirmation: "About to promote N patterns — confirm? [Y/n]"
+
+## Configuration
+
+In `config.json`:
+```json
+{
+  "learning": {
+    "promotionThreshold": 3,
+    "autoPromoteEnabled": false,
+    "requireUserConfirmation": true
+  }
+}
+```
+
+## Files
+
+| Action | File |
+|--------|------|
+| Read | `.workflow/state/feedback-patterns.md` |
+| Read | `.workflow/state/decisions.md` |
+| Read | `.workflow/corrections/*.md` |
+| Read | `.workflow/state/request-log.md` (for incident mode) |
+| Write | `.workflow/state/decisions.md` (new rules) |
+| Write | `.workflow/state/feedback-patterns.md` (mark promoted) |
+| Write | `.workflow/state/request-log.md` (log entry) |

package/.claude/commands/wogi-retrospective.md

@@ -0,0 +1,241 @@
+Guided session retrospective that extracts lessons from recent work. Invoke when user says "let's do a retro", "what went well", "what can we improve", or "lessons learned".
+
+## Usage
+
+```bash
+/wogi-retrospective            # Full retrospective
+/wogi-retrospective --quick    # Quick summary + one question
+```
+
+## Trigger Phrases
+
+Auto-routed from `/wogi-start` when user says:
+- "let's do a retro"
+- "what went well"
+- "what can we improve"
+- "session retrospective"
+- "lessons learned"
+
+## How It Works
+
+### Step 0: Check for Session History
+
+Read `.workflow/state/request-log.md` and check for recent entries (since last session end or last retro).
+
+**If no recent work:**
+```
+No recent work to reflect on.
+
+Start working with `/wogi-start` first, then run a retro
+after completing some tasks.
+```
+Stop here.
+
+### Step 1: Gather Session Data
+
+Read these files to build a session picture:
+
+1. **`.workflow/state/request-log.md`** — Recent entries (since last session end marker or last 10 entries)
+   - Extract: task IDs, types, results, files changed
+2. **`.workflow/state/last-review.json`** — Last review findings (if exists)
+   - Extract: finding count, severities, categories
+3. **`.workflow/corrections/`** — Recent correction reports
+   - Extract: patterns, root causes, lessons
+4. **`.workflow/state/feedback-patterns.md`** — Recurring patterns
+   - Extract: high-count patterns, recently added patterns
+5. **`.workflow/state/ready.json`** — Task completion data
+   - Extract: recently completed tasks, in-progress tasks
+
+### Step 2: Present Session Summary
+
+```
+Session Retrospective
+=====================
+
+Completed Work:
+  - [N] tasks completed
+  - [List task titles from request-log/ready.json recentlyCompleted]
+
+Issues Found:
+  - [N] review findings ([X] critical, [Y] high, [Z] medium)
+  - [N] corrections recorded
+  - [List significant issues]
+
+Emerging Patterns:
+  - [Pattern name] ([N] occurrences) — [description]
+  - [Pattern name] ([N] occurrences) — [description]
+
+Workflow Health:
+  - Bypass attempts: [N] (from session context)
+  - Tasks completed via workflow: [N]
+```
+
+### Step 3: Guided Reflection Questions
+
+Use `AskUserQuestion` to ask reflection questions. Ask 2-3 questions max based on what's relevant:
+
+**Always ask:**
+1. "What went well this session that we should keep doing?"
+   - Options: specific things user can select, plus "Other" for free text
+
+**Ask if issues were found:**
+2. "What was frustrating or could be improved?"
+   - Options: based on actual issues found in the data
+
+**Ask if patterns are emerging:**
+3. "Any conventions or rules that should be established from this session?"
+   - Options: based on patterns near promotion threshold
+
+**Ask if rule violations occurred:**
+4. "Did any existing rules get violated that need strengthening?"
+   - Options: based on review findings matching decisions.md rules
+
+**Maximum 3 questions per retro. Priority order when all conditions apply:**
+1. Q1 (always — "what went well")
+2. Q4 (violations — most actionable)
+3. Q3 (patterns — near promotion)
+4. Q2 (frustrations — least actionable)
+
+**Pick top 3 by this priority order.**
+
+### Step 4: Process Responses and Capture Lessons
+
+For each user response, classify and route:
+
+| Response Type | Action |
+|---------------|--------|
+| New rule/convention | Route to `/wogi-decide` flow |
+| Pattern to promote | Route to `/wogi-learn` flow |
+| Process improvement | Add to `feedback-patterns.md` |
+| Positive feedback | Acknowledge and note in retro summary |
+| Specific fix needed | Create task in `ready.json` backlog |
+
+### Step 5: Save Retro Summary
+
+Create `.workflow/reviews/retro-YYYY-MM-DD-HHMMSS.md` (include time to avoid same-day collisions):
+
+```markdown
+# Session Retrospective — YYYY-MM-DD
+
+## Session Summary
+- Tasks completed: N
+- Issues found: N (X critical, Y high)
+- Corrections: N
+- Bypass attempts: N
+
+## Completed Work
+- [task-id]: [title] — [result]
+- [task-id]: [title] — [result]
+
+## Issues & Patterns
+- [issue/pattern summary]
+
+## Reflection
+### What went well
+[User's response]
+
+### What could improve
+[User's response]
+
+### Actions Taken
+- [Action 1]: [what was done — rule created / pattern promoted / task created]
+- [Action 2]: [what was done]
+
+## Metrics
+- Review findings resolved: N/M
+- Patterns promoted: N
+- New rules created: N
+```
+
+### Step 6: Update Request Log
+
+```markdown
+### R-[NNN] | [YYYY-MM-DD HH:MM]
+**Type**: new
+**Tags**: #retro #learning
+**Request**: "Session retrospective"
+**Result**: Retro completed. [N] lessons captured. [M] actions taken.
+**Files**: `.workflow/reviews/retro-YYYY-MM-DD-HHMMSS.md`
+```
+
+### Step 7: Closing
+
+```
+Retrospective Complete
+
+Summary saved to: .workflow/reviews/retro-YYYY-MM-DD-HHMMSS.md
+
+Actions taken:
+- [N] new rules created (via /wogi-decide)
+- [N] patterns promoted (via /wogi-learn)
+- [N] improvement items captured
+- [N] tasks created for fixes
+
+Next session will benefit from these learnings.
+```
+
+---
+
+## Quick Retrospective (`--quick`)
+
+When invoked with `--quick`:
+
+1. Read the same data sources (Step 1)
+2. Display abbreviated summary:
+
+```
+Quick Retro
+===========
+Completed: [N] tasks
+Issues: [N] findings
+Bypasses: [N]
+```
+
+3. Ask one question:
+
+```
+Anything to capture before we move on?
+1. No, all good
+2. Yes, I want to add a rule
+3. Yes, I want to note a pattern
+4. Yes, I have feedback
+```
+
+4. Route response and save minimal retro file
+5. Done
+
+---
+
+## Options
+
+- `--quick` — Abbreviated flow: summary + one question
+- `--since YYYY-MM-DD` — Retro for work since specific date. **Validate**: must match `/^\d{4}-\d{2}-\d{2}$/`. Reject any other format.
+- `--no-save` — Don't save retro file (just display)
+
+## Configuration
+
+In `config.json`:
+```json
+{
+  "retrospective": {
+    "maxQuestions": 3,
+    "autoSuggestRules": true,
+    "saveReviewFile": true,
+    "quickModeDefault": false
+  }
+}
+```
+
+## Files
+
+| Action | File |
+|--------|------|
+| Read | `.workflow/state/request-log.md` |
+| Read | `.workflow/state/last-review.json` |
+| Read | `.workflow/corrections/*.md` |
+| Read | `.workflow/state/feedback-patterns.md` |
+| Read | `.workflow/state/ready.json` |
+| Write | `.workflow/reviews/retro-YYYY-MM-DD-HHMMSS.md` |
+| Write | `.workflow/state/request-log.md` |
+| May invoke | `/wogi-decide` (for new rules) |
+| May invoke | `/wogi-learn` (for pattern promotions) |