ace-retro 0.16.0

data/docs/usage.md

@@ -0,0 +1,141 @@
+---
+doc-type: user
+purpose: CLI reference for ace-retro commands and options.
+ace-docs:
+  last-updated: '2026-03-22'
+---
+
+# ace-retro CLI Reference
+
+Complete command reference for `ace-retro`.
+
+## Installation
+
+```bash
+gem install ace-retro
+```
+
+## Global Options
+
+All commands support:
+
+| Flag | Description |
+|------|-------------|
+| `-q`, `--quiet` | Suppress non-essential output |
+| `-v`, `--verbose` | Show verbose output |
+| `-d`, `--debug` | Show debug output |
+| `-h`, `--help` | Show command help |
+
+## Commands
+
+### ace-retro create TITLE
+
+Create a new retrospective.
+
+| Option | Alias | Description |
+|--------|-------|-------------|
+| `--type` | `-t` | Retro type: `standard`, `conversation-analysis`, `self-review` |
+| `--tags` | `-T` | Comma-separated tags |
+| `--move-to` | `-m` | Create directly in a target folder (for example `archive`) |
+| `--dry-run` | `-n` | Preview without writing |
+| `--gc`, `--git-commit` | | Auto-commit changes |
+
+```bash
+ace-retro create "Sprint Review" --type standard --tags sprint,team
+ace-retro create "Session Review" --type conversation-analysis
+ace-retro create "Release Retro" --move-to archive
+```
+
+### ace-retro show REF
+
+Show one retro by full 6-char ID or 3-char shortcut.
+
+| Option | Description |
+|--------|-------------|
+| `--path` | Print file path only |
+| `--content` | Print raw markdown content |
+
+```bash
+ace-retro show q7w
+ace-retro show 8ppq7w --path
+ace-retro show q7w --content
+```
+
+### ace-retro list
+
+List retros with optional filtering.
+
+| Option | Alias | Description |
+|--------|-------|-------------|
+| `--status` | `-s` | Filter by status (`active`, `done`) |
+| `--type` | `-t` | Filter by type |
+| `--tags` | `-T` | Filter by tags (comma-separated, any match) |
+| `--in` | `-i` | Folder scope: `next` (root only), `all`, `archive` |
+| `--root` | `-r` | Override retros root path |
+
+```bash
+ace-retro list
+ace-retro list --in all
+ace-retro list --in archive --type standard
+ace-retro list --status active --tags sprint,team
+```
+
+### ace-retro update REF
+
+Update frontmatter fields and/or move a retro between folders.
+
+| Option | Description |
+|--------|-------------|
+| `--set` | Set scalar metadata: `key=value` (repeatable) |
+| `--add` | Add to array field: `key=value` (repeatable) |
+| `--remove` | Remove from array field: `key=value` (repeatable) |
+| `--move-to`, `-m` | Move retro to folder (`archive`, `next`) |
+| `--gc`, `--git-commit` | Auto-commit changes |
+
+```bash
+ace-retro update q7w --set status=done
+ace-retro update q7w --set status=done --set title="Refined title"
+ace-retro update q7w --add tags=reviewed --remove tags=in-progress
+ace-retro update q7w --set status=done --move-to archive
+```
+
+### ace-retro doctor
+
+Run health checks across retros.
+
+| Option | Alias | Description |
+|--------|-------|-------------|
+| `--auto-fix` | `-f` | Auto-fix safe issues |
+| `--auto-fix-with-agent` | | Auto-fix then launch agent for unresolved items |
+| `--model` | | Provider:model for agent session |
+| `--errors-only` | | Show only errors |
+| `--no-color` | | Disable colored output |
+| `--json` | | Emit JSON output |
+| `--dry-run` | `-n` | Preview fixes without applying |
+| `--check` | | Limit to check: `frontmatter` (YAML metadata block at file top), `structure`, `scope` |
+
+```bash
+ace-retro doctor
+ace-retro doctor --auto-fix
+ace-retro doctor --auto-fix --dry-run
+ace-retro doctor --check frontmatter
+ace-retro doctor --json
+```
+
+## Common Commands
+
+| Command | What it does |
+|---------|-------------|
+| `ace-retro create "..." --type standard` | Create a retrospective |
+| `ace-retro show <ref>` | Display one retro |
+| `ace-retro list --in all` | List active and archived retros |
+| `ace-retro update <ref> --set status=done` | Update metadata |
+| `ace-retro update <ref> --move-to archive` | Archive a retro |
+| `ace-retro doctor` | Validate retro health |
+
+## Runtime Help
+
+```bash
+ace-retro help
+ace-retro <command> --help
+```

data/exe/ace-retro

@@ -0,0 +1,22 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/ace/retro"
+require_relative "../lib/ace/retro/cli"
+
+# No args → show help
+args = ARGV.empty? ? ["--help"] : ARGV
+
+# Handle SIGINT with exit code 130
+trap("INT") { exit 130 }
+
+# Start ace-support-cli with exception-based exit code handling (per ADR-023)
+begin
+  Ace::Retro::RetroCLI.start(args)
+rescue Ace::Support::Cli::Error => e
+  warn e.message
+  exit(e.exit_code)
+rescue ArgumentError => e
+  warn "Error: #{e.message}"
+  exit(1)
+end

data/handbook/skills/as-handbook-selfimprove/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: as-handbook-selfimprove
+description: Analyze mistakes to improve processes, then fix the immediate issue
+# bundle: wfi://retro/selfimprove
+# agent: general-purpose
+user-invocable: true
+allowed-tools:
+  - Bash(ace-bundle:*)
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+argument-hint: [description of what went wrong]
+last_modified: 2026-03-10
+source: ace-retro
+integration:
+  targets:
+    - claude
+    - codex
+    - gemini
+    - opencode
+    - pi
+  providers: {}
+skill:
+  kind: workflow
+  execution:
+    workflow: wfi://retro/selfimprove
+---
+
+Load and run `ace-bundle wfi://retro/selfimprove` in the current project, then follow the loaded workflow as the source of truth and execute it end-to-end instead of only summarizing it.

data/handbook/skills/as-retro-create/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: as-retro-create
+description: Create task retrospective documenting learnings and improvements
+# bundle: wfi://retro/create
+# context: no-fork
+# agent: general-purpose
+user-invocable: true
+allowed-tools:
+  - Bash(ace-task:*)
+  - Bash(ace-bundle:*)
+  - Bash(ace-git-commit:*)
+  - Read
+  - Write
+  - TodoWrite
+argument-hint: [retro-title]
+last_modified: 2026-01-10
+source: ace-task
+skill:
+  kind: workflow
+  execution:
+    workflow: wfi://retro/create
+
+---
+
+Load and run `ace-bundle wfi://retro/create` in the current project, then follow the loaded workflow as the source of truth and execute it end-to-end instead of only summarizing it.
+

data/handbook/skills/as-retro-synthesize/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: as-retro-synthesize
+description: Synthesize retrospectives into patterns and improvement recommendations
+# bundle: wfi://retro/synthesize
+# context: no-fork
+# agent: general-purpose
+user-invocable: true
+allowed-tools:
+  - Bash(ace-task:*)
+  - Bash(ace-bundle:*)
+  - Bash(ace-git-commit:*)
+  - Read
+  - Write
+  - Grep
+  - TodoWrite
+last_modified: 2026-01-10
+source: ace-task
+skill:
+  kind: workflow
+  execution:
+    workflow: wfi://retro/synthesize
+
+---
+
+Load and run `ace-bundle wfi://retro/synthesize` in the current project, then follow the loaded workflow as the source of truth and execute it end-to-end instead of only summarizing it.
+

data/handbook/templates/retro/retro.template.md

@@ -0,0 +1,194 @@
+---
+doc-type: template
+title: "Reflection: [Topic/Date]"
+purpose: Documentation for ace-retro/handbook/templates/retro/retro.template.md
+ace-docs:
+  last-updated: 2026-03-01
+  last-checked: 2026-03-21
+---
+
+# Reflection: [Topic/Date]
+
+**Date**: YYYY-MM-DD
+**Context**: [Brief description of what this reflection covers]
+**Author**: [Name or identifier]
+**Type**: [Standard | Conversation Analysis | Self-Review]
+
+## What Went Well
+
+- [Positive outcome or successful approach]
+- [Effective pattern discovered]
+- [Good decision that paid off]
+
+## What Could Be Improved
+
+- [Challenge encountered]
+- [Inefficiency identified]
+- [Area needing attention]
+
+## Key Learnings
+
+- [Important insight gained]
+- [New understanding developed]
+- [Valuable lesson learned]
+
+## Conversation Analysis (For conversation-based reflections)
+
+### Challenge Patterns Identified
+
+#### High Impact Issues
+
+- **[Challenge Type]**: [Description]
+  - Occurrences: [Number of times this pattern appeared]
+  - Impact: [Description of delays/rework caused]
+  - Root Cause: [Analysis of underlying issue]
+
+#### Medium Impact Issues
+
+- **[Challenge Type]**: [Description]
+  - Occurrences: [Number of times this pattern appeared]
+  - Impact: [Description of inefficiencies caused]
+
+#### Low Impact Issues
+
+- **[Challenge Type]**: [Description]
+  - Occurrences: [Number of times this pattern appeared]
+  - Impact: [Minor inconveniences]
+
+### Improvement Proposals
+
+#### Process Improvements
+
+- [Specific workflow enhancement]
+- [Documentation improvement]
+- [Better validation step]
+
+#### Tool Enhancements
+
+- [Command improvement suggestion]
+- [Tool capability request]
+- [Automation opportunity]
+
+#### Communication Protocols
+
+- [Clearer requirement gathering]
+- [Better confirmation process]
+- [Enhanced feedback loop]
+
+### Token Limit & Truncation Issues
+
+- **Large Output Instances**: [Count and description]
+- **Truncation Impact**: [Information lost, workflow disruption]
+- **Mitigation Applied**: [How issues were resolved]
+- **Prevention Strategy**: [Future avoidance approach]
+
+## Action Items
+
+### Stop Doing
+
+- [Practice or approach to discontinue]
+- [Ineffective pattern to avoid]
+
+### Continue Doing
+
+- [Successful practice to maintain]
+- [Effective approach to keep using]
+
+### Start Doing
+
+- [New practice to adopt]
+- [Improvement to implement]
+
+## Technical Details
+
+(Optional: Specific technical insights, code patterns, or implementation notes)
+
+## Automation Insights
+
+### Identified Opportunities
+
+- **[Process/Task Name]**: [What could be automated]
+  - Current approach: [How it's done manually now]
+  - Automation proposal: [How it could be automated]
+  - Expected time savings: [Estimated reduction in effort]
+  - Implementation complexity: [Low/Medium/High]
+
+### Priority Automations
+
+1. **[High Priority Item]**: [Brief description and impact]
+2. **[Medium Priority Item]**: [Brief description and impact]
+3. **[Low Priority Item]**: [Brief description and impact]
+
+## Tool Proposals
+
+### Missing Dev-Tools
+
+- **Tool Name**: `[proposed-command-name]`
+  - Purpose: [What problem it solves]
+  - Expected usage: `[example command usage]`
+  - Key features: [Main capabilities needed]
+  - Similar to: [Existing tools it relates to, if any]
+
+### Enhancement Requests
+
+- **Existing Tool**: `[tool-name]`
+  - Enhancement: [What capability to add]
+  - Use case: [Why this enhancement is needed]
+  - Workaround: [Current alternative approach]
+
+## Workflow Proposals
+
+### New Workflows Needed
+
+- **Workflow Name**: `[workflow-name].wf.md`
+  - Purpose: [What process it would streamline]
+  - Trigger: [When/how it would be invoked]
+  - Key steps: [High-level process outline]
+  - Expected frequency: [How often it would be used]
+
+### Workflow Enhancements
+
+- **Existing Workflow**: `[workflow-name].wf.md`
+  - Enhancement: [What to improve]
+  - Rationale: [Why this change would help]
+  - Impact: [Benefits of the enhancement]
+
+## Cookbook Opportunities
+
+### Patterns Worth Documenting
+
+- **Pattern Name**: [Descriptive name for the pattern]
+  - Context: [When this pattern applies]
+  - Solution approach: [Core technique or method]
+  - Example scenario: [Concrete use case]
+  - Reusability: [How often this comes up]
+
+### Proposed Cookbooks
+
+- **Cookbook Title**: `[cookbook-name].cookbook.md`
+  - Problem it solves: [Clear problem statement]
+  - Target audience: [Who would benefit]
+  - Prerequisites: [Required knowledge/tools]
+  - Key sections: [Main topics to cover]
+
+## Pattern Identification
+
+### Reusable Code Snippets
+
+- **Snippet Purpose**: [What it accomplishes]
+  ```[language]
+  # Code snippet or pattern
+  ```
+  - Use cases: [Where this could be reused]
+  - Variations: [How it might be adapted]
+
+### Template Opportunities
+
+- **Template Type**: [What kind of template]
+  - Common structure: [Repeated pattern identified]
+  - Variables needed: [What would be parameterized]
+  - Expected usage: [How often it would be used]
+
+## Additional Context
+
+(Optional: Links to relevant PRs, tasks, or documentation)

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

@@ -0,0 +1,141 @@
+---
+doc-type: workflow
+title: Create Retro Workflow Instruction
+purpose: Documentation for ace-retro/handbook/workflow-instructions/retro/create.wf.md
+ace-docs:
+  last-updated: 2026-03-01
+  last-checked: 2026-03-21
+---
+
+# Create Retro Workflow Instruction
+
+## Goal
+
+Capture observations, learnings, and improvement ideas from development work. Retros document insights that help improve future processes and outcomes.
+
+## Prerequisites
+
+- Understanding of what to capture (learnings, challenges, improvements)
+- Current working session or specific context to reflect upon
+
+## Process Steps
+
+### 1. Determine Retro Context
+
+Identify the scope and subject of the retro:
+
+- **User-provided topic**: Use the specific topic, task, or time period given
+- **Current session**: Self-review the working session for patterns and learnings
+- **Task completion**: Reflect on a completed task or feature
+
+### 2. Generate a Slug
+
+Create a concise, descriptive slug from the topic:
+
+- Use lowercase with hyphens: `oauth-integration-challenges`
+- Keep it short but descriptive: `sprint-23-learnings`
+- Include relevant context: `ace-test-runner-fixes`
+
+### 3. Create the Retro File
+
+```bash
+# Basic creation
+ace-retro create "topic-slug"
+
+# With type and tags
+ace-retro create "topic-slug" --type standard --tags sprint,team
+```
+
+Read the created file path from the command output.
+
+### 4. Populate the Retro
+
+Use the template format from `tmpl://retro/retro` to structure content. Fill each section with meaningful insights from the retro context.
+
+**Core sections to populate:**
+
+- **What Went Well** — successful approaches, effective patterns, good decisions
+- **What Could Be Improved** — challenges, inefficiencies, areas needing attention
+- **Key Learnings** — insights gained, new understanding, valuable lessons
+- **Action Items** — stop/continue/start doing items
+
+**Optional enhancement sections** (use when relevant):
+
+- Automation Insights
+- Tool Proposals
+- Workflow Proposals
+
+### 5. Gather Content via Reflection
+
+**Reflection Prompts:**
+
+- What was the main goal of this work?
+- What obstacles were encountered?
+- How were problems solved?
+- What would you do differently?
+- What patterns emerged?
+- What knowledge was gained?
+
+**For session-based retros**, review:
+
+- Recent git commits and changes
+- Challenges faced and how they were resolved
+- Successful approaches worth repeating
+
+**When review session data is available** (e.g., after review cycles in an assignment), analyze:
+
+- Review sessions in `.ace-local/review/sessions/` for the current branch/PR
+- Load each session's `feedback-synthesis/feedback-synthesis.cleaned.json` for structured findings
+- Load each session's `metadata.yml` for model performance data (duration, success rate)
+
+Cross-cycle review analysis prompts:
+
+- Which feedback items recurred across cycles? (indicates systematic issues vs. one-off nits)
+- What was the false-positive rate per reviewer model? (findings marked invalid without code changes)
+- How did severity calibration differ across models? (e.g., one model flags high-priority items that others miss)
+- Did later review cycles (code-fit, code-shine) catch qualitatively different issues than early ones (code-valid)?
+- What percentage of feedback items led to actual code changes vs. being dismissed?
+
+Capture these observations in the retro under a **Review Cycle Analysis** subsection within "Key Learnings".
+
+### 6. Finalize
+
+- Ensure populated sections have meaningful content
+- Remove empty optional sections
+- Verify with `ace-retro list` to confirm the retro appears
+
+### 7. Commit the Retro
+
+Commit the retro file so the artifact is preserved in the branch history:
+
+```bash
+ace-git-commit .ace-retros/ -i "retro for <context>"
+```
+
+This is especially important when running inside a fork subtree, where uncommitted files would be lost when the fork process exits.
+
+## Best Practices
+
+**DO:**
+
+- Be honest about challenges and failures
+- Focus on actionable improvements
+- Include specific examples
+- Keep entries concise but complete
+- Date and contextualize retros
+
+**DON'T:**
+
+- Make it a blame session
+- Be vague or generic
+- Skip the action items
+- Leave sections empty without removing them
+- Write novels — keep it focused
+
+## Success Criteria
+
+- Retro created via `ace-retro create` with appropriate slug
+- Key sections populated with meaningful content
+- Action items clearly defined
+- Insights captured for future reference
+- Retro file committed to the branch