ace-retro 0.16.0

data/handbook/workflow-instructions/retro/selfimprove.wf.md

@@ -0,0 +1,197 @@
+---
+doc-type: workflow
+title: Self-Improve Workflow
+purpose: Documentation for ace-retro/handbook/workflow-instructions/retro/selfimprove.wf.md
+ace-docs:
+  last-updated: 2026-03-01
+  last-checked: 2026-03-21
+---
+
+# Self-Improve Workflow
+
+## Goal
+
+Transform mistakes and recurring issues into system improvements. Fix the process first, then fix the immediate issue.
+
+## Anti-Pattern
+
+❌ Mistake happens → Agent re-runs instruction → Same mistake can happen again
+
+## Correct Pattern
+
+✅ Mistake identified → Analyze root cause → Update process → Fix immediate issue → Record retro
+
+## Input Sources
+
+Self-improvement is always a consequence of retrospective. Input can come from:
+
+- **Session context** — analyze current conversation for mistakes or suboptimal patterns
+- **Existing retros** — load retros via `ace-retro list`/`ace-retro show` to find recurring issues
+- **User input** — user describes what went wrong
+
+## Process Steps
+
+### Step 1: Gather Input
+
+Determine the source and capture incident details:
+
+**From session context:**
+- Review the current conversation for mistakes, repeated attempts, or corrections
+- Identify what went wrong and what should have happened
+
+**From existing retros:**
+```bash
+# Find retros with relevant issues
+ace-retro list --status active
+
+# Load specific retro content
+ace-retro show REF --content
+```
+
+**From user input:**
+- Capture the user's description of the problem
+
+Document the incident:
+
+| Question | Details |
+|----------|---------|
+| **What happened** | What action was taken? |
+| **Actual result** | What was the output? |
+| **Expected result** | What should have happened? |
+| **Source** | Session / retro REF / user description |
+
+### Step 2: Identify Root Cause Category
+
+Ask: "Why did this happen?" Categorize the root cause:
+
+| Category | Description | Example |
+|----------|-------------|---------|
+| **Ambiguous instructions** | Workflow allows misinterpretation | "Reorganize commits" without specifying scope source |
+| **Missing validation** | No checkpoint to catch the error | No step to verify scope before executing |
+| **Assumed context** | Agent didn't have necessary information | Agent used plan data instead of querying actual state |
+| **Scope narrowing** | Agent under-scoped the task | Followed plan literally instead of understanding intent |
+| **Scope creep** | Agent over-scoped the task | Made changes beyond what was requested |
+| **Missing example** | No example of correct behavior | Workflow lacks example showing full scope discovery |
+| **Redundant computation** | Multiple agents derive same value independently, causing divergence | Orchestrator computes path one way, agent re-derives differently |
+
+### Step 3: Find the Source
+
+Search for the relevant process files that need updating:
+
+```bash
+# Search workflow instructions
+ace-bundle wfi://{relevant-workflow}
+
+# Search guides
+ace-bundle guide://{relevant-guide}
+
+# Search skills
+ace-bundle skill://{relevant-skill}
+
+# Discover available resources
+ace-nav --sources
+```
+
+**Search targets (in preference order):**
+
+1. **Workflow instructions** (`wfi://namespace/action`) — preferred for process improvements
+2. **Guides** (`guide://topic`) — preferred for best practices and conventions
+3. **Skills** (`.claude/skills/*/SKILL.md`) — only when workflow/guide doesn't exist
+4. **CLAUDE.md files** — project-level overrides only
+
+### Step 4: Draft the Fix
+
+Propose specific edits. The fix should:
+
+1. **Address the root cause** — not just the symptom
+2. **Be minimal** — only change what's necessary
+3. **Include validation** — add checkpoints where missing
+4. **Add examples** — show correct behavior if unclear
+
+**Fix templates by category:**
+
+**For ambiguous instructions:**
+```markdown
+## After
+**Scope Discovery**: Before executing, always query the actual state:
+- Run the relevant query command to get the full scope
+- Do NOT rely on estimates — query actual state
+- Confirm scope with user if actual differs from expectations
+```
+
+**For missing validation:**
+```markdown
+## After
+### Validate Before Executing
+- [ ] Query actual state
+- [ ] Compare to expected scope
+- [ ] If mismatch, confirm with user before proceeding
+```
+
+**For redundant computation:**
+```markdown
+## After
+Pass computed values explicitly; don't re-derive:
+- Orchestrator computes once and passes to subagent
+- Subagent uses the provided value, never re-derives
+```
+
+### Step 5: Present to User
+
+Before making any changes, present:
+
+```markdown
+## Root Cause Analysis
+
+**What happened**: [Concise description]
+**Why it happened**: [Root cause category and explanation]
+**Source file**: [File path(s) to update]
+
+## Proposed Process Changes
+
+**File**: `{path/to/file}`
+**Change**: [Description]
+
+**Diff preview**:
+` ``diff
+- [old content]
++ [new content]
+` ``
+
+## Questions
+
+1. Does this analysis match your understanding?
+2. Should I proceed with these process changes?
+3. After updating the process, should I also fix the immediate issue?
+```
+
+### Step 6: Implement Changes
+
+After user approval:
+
+1. **Update the process file(s)** — apply the proposed edits
+2. **Fix the immediate issue** (if requested)
+3. **Record a retro** documenting the improvement:
+
+```bash
+ace-retro create "selfimprove-TOPIC" --type self-improvement --tags process-fix
+```
+
+Populate the retro with the root cause analysis, the fix applied, and the expected impact.
+
+### Step 7: Archive Consumed Retros
+
+If the input source was an existing retro, archive it after the improvement has been applied — the retro has been "consumed":
+
+```bash
+ace-retro move REF --to archive
+```
+
+## Success Criteria
+
+- Root cause is identified (not just symptoms)
+- Process fix prevents recurrence
+- User approves changes before implementation
+- Both process and immediate issue are addressed
+- Improvement is recorded as a retro via `ace-retro create`
+- Source retros (if any) are archived after processing

data/handbook/workflow-instructions/retro/synthesize.wf.md

@@ -0,0 +1,94 @@
+---
+doc-type: workflow
+title: Synthesize Retros Workflow Instruction
+purpose: Documentation for ace-retro/handbook/workflow-instructions/retro/synthesize.wf.md
+ace-docs:
+  last-updated: 2026-03-01
+  last-checked: 2026-03-21
+---
+
+# Synthesize Retros Workflow Instruction
+
+## Goal
+
+Reduce multiple retros into a single synthesis retro. Distill common themes, recurring issues, and shared action items from N input retros into one consolidated retro using the standard retro format.
+
+## Prerequisites
+
+- At least 2 active retros exist to synthesize
+- Access to `ace-retro` CLI
+
+## Process Steps
+
+### 1. Gather Retros
+
+Find candidate retros for synthesis:
+
+```bash
+# List active retros
+ace-retro list --status active
+
+# Filter by tags if synthesizing a specific topic
+ace-retro list --status active --tags TAG
+```
+
+Select which retros to include. Good candidates share a common theme, time period, or tag.
+
+### 2. Load Content
+
+Read each selected retro:
+
+```bash
+ace-retro show REF --content
+```
+
+Collect the content from all selected retros before proceeding to analysis.
+
+### 3. Reduce
+
+Analyze all input retros together. Identify:
+
+- **Common themes** — issues or observations that appear across multiple retros
+- **Recurring patterns** — problems or successes that repeat
+- **Shared action items** — improvements suggested in multiple retros
+- **Contradictions** — conflicting recommendations that need resolution
+- **Unique insights** — one-off observations worth preserving
+
+For each theme, note which source retros contributed to it and how frequently it appeared.
+
+### 4. Create Synthesis Retro
+
+```bash
+ace-retro create "synthesis-TOPIC" --tags synthesis
+```
+
+Read the created file path from the output.
+
+### 5. Populate
+
+Fill the synthesis retro using the standard template format (`tmpl://retro/retro`). The content is distilled from the N input retros:
+
+- **What Went Well** — patterns of success across multiple retros, validated approaches
+- **What Could Be Improved** — recurring issues, systemic problems identified across retros
+- **Key Learnings** — consolidated insights, with frequency noted where relevant
+- **Action Items** — merged and deduplicated action items, prioritized by how often they appeared
+
+When populating, reference source retros to provide traceability (e.g., "Identified in 3/5 retros").
+
+### 6. Archive Sources
+
+After the synthesis retro is populated and complete, archive each source retro — they have been "consumed" by the synthesis:
+
+```bash
+ace-retro move REF --to archive
+```
+
+Repeat for each source retro.
+
+## Success Criteria
+
+- Synthesis retro created using standard retro format
+- Common themes and recurring patterns identified across inputs
+- Action items deduplicated and prioritized by frequency
+- Source retros archived after processing
+- Output is a single retro that stands on its own — no external templates or analytics needed

data/lib/ace/retro/atoms/retro_file_pattern.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Ace
+  module Retro
+    module Atoms
+      # Provides glob patterns for finding retro files.
+      # Retros use the .retro.md extension.
+      module RetroFilePattern
+        # Glob pattern for retro files within a directory
+        FILE_GLOB = "*.retro.md"
+
+        # Full file extension for retro files
+        FILE_EXTENSION = ".retro.md"
+
+        # Build the retro filename
+        # @param id [String] Raw 6-char b36ts ID
+        # @param slug [String] Kebab-case slug
+        # @return [String] Retro filename (e.g., "8ppq7w-sprint-review.retro.md")
+        def self.retro_filename(id, slug)
+          "#{id}-#{slug}#{FILE_EXTENSION}"
+        end
+
+        # Build the folder name for a retro
+        # @param id [String] Raw 6-char b36ts ID
+        # @param slug [String] Kebab-case slug
+        # @return [String] Folder name (e.g., "8ppq7w-sprint-review")
+        def self.folder_name(id, slug)
+          "#{id}-#{slug}"
+        end
+
+        # Check if a filename matches the retro file pattern
+        # @param filename [String] Filename to check
+        # @return [Boolean] True if it's a retro file
+        def self.retro_file?(filename)
+          filename.to_s.end_with?(FILE_EXTENSION)
+        end
+      end
+    end
+  end
+end

data/lib/ace/retro/atoms/retro_frontmatter_defaults.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Ace
+  module Retro
+    module Atoms
+      # Provides default frontmatter values for retro files.
+      # Generates the canonical YAML frontmatter block for new retros.
+      module RetroFrontmatterDefaults
+        # Build frontmatter hash for a new retro
+        # @param id [String] Raw 6-char b36ts ID
+        # @param title [String] Retro title
+        # @param type [String] Retro type (standard, conversation-analysis, self-review)
+        # @param tags [Array<String>] List of tags (default: [])
+        # @param status [String] Initial status (default: "active")
+        # @param created_at [Time] Creation time (default: now)
+        # @return [Hash] Frontmatter hash ready for YAML serialization
+        def self.build(id:, title:, type: "standard", tags: [], status: "active",
+          created_at: Time.now.utc)
+          {
+            "id" => id,
+            "title" => title,
+            "type" => type,
+            "tags" => Array(tags),
+            "created_at" => created_at.strftime("%Y-%m-%d %H:%M:%S"),
+            "status" => status
+          }
+        end
+
+        # Serialize frontmatter hash to YAML block string.
+        # Delegates to the shared FrontmatterSerializer atom.
+        # @param frontmatter [Hash] Frontmatter data
+        # @return [String] YAML frontmatter block including delimiters
+        def self.serialize(frontmatter)
+          require "ace/support/items"
+          Ace::Support::Items::Atoms::FrontmatterSerializer.serialize(frontmatter)
+        end
+      end
+    end
+  end
+end

data/lib/ace/retro/atoms/retro_id_formatter.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "ace/b36ts"
+
+module Ace
+  module Retro
+    module Atoms
+      # Generates and formats raw b36ts IDs for retros.
+      # Retros use raw 6-char b36ts IDs without type markers.
+      # Example: "8ppq7w" (no ".t." or ".i." separator)
+      class RetroIdFormatter
+        # Generate a new raw 6-char b36ts ID for a retro
+        # @param time [Time] Time to encode (default: now)
+        # @return [String] 6-character raw b36ts ID (e.g., "8ppq7w")
+        def self.generate(time = Time.now.utc)
+          Ace::B36ts.encode(time, format: :"2sec")
+        end
+
+        # Validate that a string is a valid raw retro ID
+        # @param id [String] The ID to validate
+        # @return [Boolean] True if valid 6-char b36ts ID
+        def self.valid?(id)
+          return false if id.nil? || id.empty?
+
+          Ace::B36ts.valid?(id)
+        end
+
+        # Decode a raw retro ID to the time it was created
+        # @param id [String] Raw 6-char b36ts ID
+        # @return [Time] The time encoded in the ID
+        def self.decode_time(id)
+          Ace::B36ts.decode(id)
+        end
+      end
+    end
+  end
+end

data/lib/ace/retro/atoms/retro_validation_rules.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require_relative "retro_id_formatter"
+
+module Ace
+  module Retro
+    module Atoms
+      # Pure validation predicates and constants for retro health checking.
+      # Used by doctor validators to determine correctness of frontmatter,
+      # file structure, and scope/status consistency.
+      module RetroValidationRules
+        VALID_STATUSES = %w[active done].freeze
+        TERMINAL_STATUSES = %w[done].freeze
+        REQUIRED_FIELDS = %w[id title type status created_at].freeze
+        RECOMMENDED_FIELDS = %w[tags].freeze
+
+        # Check if a status string is valid
+        # @param status [String] Status to validate
+        # @return [Boolean]
+        def self.valid_status?(status)
+          VALID_STATUSES.include?(status.to_s)
+        end
+
+        # Check if a status is terminal (belongs in _archive)
+        # @param status [String] Status to check
+        # @return [Boolean]
+        def self.terminal_status?(status)
+          TERMINAL_STATUSES.include?(status.to_s)
+        end
+
+        # Check if an ID string is a valid b36ts retro ID
+        # @param id [String] ID to validate
+        # @return [Boolean]
+        def self.valid_id?(id)
+          RetroIdFormatter.valid?(id)
+        end
+
+        # Check if scope (special folder) is consistent with status
+        # @param status [String] Retro status
+        # @param special_folder [String, nil] Special folder name (e.g., "_archive", nil)
+        # @return [Array<Hash>] List of inconsistency issues (empty if consistent)
+        def self.scope_consistent?(status, special_folder)
+          issues = []
+
+          if terminal_status?(status) && special_folder != "_archive"
+            issues << {
+              type: :warning,
+              message: "Retro with terminal status '#{status}' not in _archive/"
+            }
+          end
+
+          if special_folder == "_archive" && !terminal_status?(status) && status
+            issues << {
+              type: :warning,
+              message: "Retro in _archive/ but status is '#{status}' (expected terminal status)"
+            }
+          end
+
+          issues
+        end
+
+        # Return list of missing required fields from frontmatter
+        # @param frontmatter [Hash] Parsed frontmatter
+        # @return [Array<String>] Names of missing required fields
+        def self.missing_required_fields(frontmatter)
+          return REQUIRED_FIELDS.dup if frontmatter.nil? || !frontmatter.is_a?(Hash)
+
+          REQUIRED_FIELDS.select { |field| frontmatter[field].nil? || frontmatter[field].to_s.strip.empty? }
+        end
+
+        # Return list of missing recommended fields from frontmatter
+        # @param frontmatter [Hash] Parsed frontmatter
+        # @return [Array<String>] Names of missing recommended fields
+        def self.missing_recommended_fields(frontmatter)
+          return RECOMMENDED_FIELDS.dup if frontmatter.nil? || !frontmatter.is_a?(Hash)
+
+          RECOMMENDED_FIELDS.select { |field| frontmatter[field].nil? }
+        end
+      end
+    end
+  end
+end

data/lib/ace/retro/cli/commands/create.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+
+module Ace
+  module Retro
+    module CLI
+      module Commands
+        # ace-support-cli Command class for ace-retro create
+        class Create < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+
+          desc <<~DESC.strip
+            Create a new retro
+
+            Creates a new retrospective with title, type, and tags.
+
+          DESC
+
+          example [
+            '"Sprint Review" --type standard --tags sprint,team        # Standard retro',
+            '"Quick self-review" --type self-review                    # Self-review retro',
+            '"Sprint Review" --move-to archive                        # Create in _archive/',
+            '"Sprint Review" --dry-run                                # Preview without writing'
+          ]
+
+          argument :title, required: false, desc: "Retro title"
+
+          option :type, type: :string, aliases: %w[-t], desc: "Retro type (standard, conversation-analysis, self-review)"
+          option :tags, type: :string, aliases: %w[-T], desc: "Comma-separated tags"
+          option :"move-to", type: :string, aliases: %w[-m], desc: "Target folder (e.g. archive)"
+          option :"dry-run", type: :boolean, aliases: %w[-n], desc: "Preview without writing"
+
+          option :git_commit, type: :boolean, aliases: %w[--gc], desc: "Auto-commit changes"
+
+          option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress non-essential output"
+          option :verbose, type: :boolean, aliases: %w[-v], desc: "Show verbose output"
+          option :debug, type: :boolean, aliases: %w[-d], desc: "Show debug output"
+
+          def call(title: nil, **options)
+            type = options[:type]
+            tags_str = options[:tags]
+            move_to = options[:"move-to"]
+            dry_run = options[:"dry-run"]
+
+            tags = tags_str ? tags_str.split(",").map(&:strip).reject(&:empty?) : []
+
+            unless title
+              warn "Error: title is required"
+              warn ""
+              warn "Usage: ace-retro create TITLE [--type TYPE] [--tags T1,T2] [--move-to FOLDER]"
+              raise Ace::Support::Cli::Error.new("Title required")
+            end
+
+            if dry_run
+              puts "Would create retro:"
+              puts "  Title:    #{title}"
+              puts "  Type:     #{type || "standard"}"
+              puts "  Tags:     #{tags.any? ? tags.join(", ") : "(none)"}"
+              puts "  Folder:   #{move_to ? "_#{move_to.delete_prefix("_")}" : "(root)"}"
+              return
+            end
+
+            manager = Ace::Retro::Organisms::RetroManager.new
+            retro = manager.create(
+              title,
+              type: type,
+              tags: tags,
+              move_to: move_to
+            )
+
+            folder_info = retro.special_folder ? " (#{retro.special_folder})" : ""
+            puts "Retro created: #{retro.id} #{retro.title}#{folder_info}"
+            puts "  Path: #{retro.file_path}"
+
+            if options[:git_commit]
+              Ace::Support::Items::Molecules::GitCommitter.commit(
+                paths: [retro.path],
+                intention: "create retro #{retro.id}"
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end