feat: rationalize todo skill names and optimize skills (#368)
This commit is contained in:
Trevin Chow
@@ -25,7 +25,10 @@ bun run release:validate # check plugin/marketplace consistency
|
||||
- **Release versioning:** Releases are prepared by release automation, not normal feature PRs. The repo now has multiple release components (`cli`, `compound-engineering`, `coding-tutor`, `marketplace`). GitHub release PRs and GitHub Releases are the canonical release-notes surface for new releases; root `CHANGELOG.md` is only a pointer to that history. Use conventional titles such as `feat:` and `fix:` so release automation can classify change intent, but do not hand-bump release-owned versions or hand-author release notes in routine PRs.
|
||||
- **Output Paths:** Keep OpenCode output at `opencode.json` and `.opencode/{agents,skills,plugins}`. For OpenCode, command go to `~/.config/opencode/commands/<name>.md`; `opencode.json` is deep-merged (never overwritten wholesale).
|
||||
- **Scratch Space:** When authoring or editing skills and agents that need repo-local scratch space, instruct them to use `.context/` for ephemeral collaboration artifacts. Namespace compound-engineering workflow state under `.context/compound-engineering/<workflow-or-skill-name>/`, add a per-run subdirectory when concurrent runs are plausible, and clean scratch artifacts up after successful completion unless the user asked to inspect them or another agent still needs them. Durable outputs like plans, specs, learnings, and docs do not belong in `.context/`.
|
||||
- **ASCII-first:** Use ASCII unless the file already contains Unicode.
|
||||
- **Character encoding:**
|
||||
- **Identifiers** (file names, agent names, command names): ASCII only -- converters and regex patterns depend on it.
|
||||
- **Markdown tables:** Use pipe-delimited (`| col | col |`), never box-drawing characters.
|
||||
- **Prose and skill content:** Unicode is fine (emoji, punctuation, etc.). Prefer ASCII arrows (`->`, `<-`) over Unicode arrows in code blocks and terminal examples.
|
||||
|
||||
## Directory Layout
|
||||
|
||||
|
||||
81
docs/solutions/workflow/todo-status-lifecycle.md
Normal file
81
docs/solutions/workflow/todo-status-lifecycle.md
Normal file
@@ -0,0 +1,81 @@
|
||||
---
|
||||
title: "Status-gated todo resolution: making pending/ready distinction load-bearing"
|
||||
category: workflow
|
||||
date: "2026-03-24"
|
||||
tags:
|
||||
- todo-system
|
||||
- status-lifecycle
|
||||
- review-pipeline
|
||||
- triage
|
||||
- safety-gate
|
||||
related_components:
|
||||
- plugins/compound-engineering/skills/todo-resolve/
|
||||
- plugins/compound-engineering/skills/ce-review/
|
||||
- plugins/compound-engineering/skills/ce-review-beta/
|
||||
- plugins/compound-engineering/skills/todo-triage/
|
||||
- plugins/compound-engineering/skills/todo-create/
|
||||
problem_type: correctness-gap
|
||||
---
|
||||
|
||||
# Status-Gated Todo Resolution
|
||||
|
||||
## Problem
|
||||
|
||||
The todo system defines a three-state lifecycle (`pending` -> `ready` -> `complete`) across three skills (`todo-create`, `todo-triage`, `todo-resolve`). Two review skills create todos with different status assumptions:
|
||||
|
||||
| Source | Status created | Reasoning |
|
||||
|--------|---------------|-----------|
|
||||
| `ce:review` | `pending` | Dumps all findings, expects separate `/todo-triage` |
|
||||
| `ce:review-beta` | `ready` | Built-in triage: confidence gating (>0.60), merge/dedup across 8 personas, owner routing. Only creates todos for `downstream-resolver` findings |
|
||||
| `todo-create` (manual) | `pending` (default) | Template default |
|
||||
| `test-browser`, `test-xcode` | via `todo-create` | Inherit default |
|
||||
|
||||
`todo-resolve` was resolving ALL todos regardless of status. This meant untriaged, potentially ambiguous findings could be auto-implemented without human review. The `pending`/`ready` distinction was purely cosmetic -- dead metadata that nothing branched on.
|
||||
|
||||
## Root Cause
|
||||
|
||||
The status field was defined in the schema but never enforced at the resolve boundary. `todo-resolve` loaded every non-complete todo and attempted to fix it, collapsing the intended `pending -> triage -> ready -> resolve` pipeline into a flat "resolve everything" approach.
|
||||
|
||||
## Solution
|
||||
|
||||
Updated `todo-resolve` to partition todos by status in its Analyze step:
|
||||
|
||||
- **`ready`** (status field or `-ready-` in filename): resolve these
|
||||
- **`pending`**: skip entirely, report at end with hint to run `/todo-triage`
|
||||
- **`complete`**: ignore
|
||||
|
||||
This is a single-file change scoped to `todo-resolve/SKILL.md`. No schema changes, no new fields, no changes to `todo-create` or `todo-triage` -- just enforcement of the existing contract at the resolve boundary.
|
||||
|
||||
## Key Insight: Review-Beta Promotion Eliminates Automated `pending`
|
||||
|
||||
Once `ce:review-beta` is promoted to stable (replacing `ce:review`), no automated source creates `pending` todos. The `pending` status becomes exclusively a human-authored state for manually created work items that need triage before action.
|
||||
|
||||
The safety model becomes:
|
||||
- **`ready`** = autofix-eligible. Triage already happened upstream (either built into the review pipeline or via explicit `/todo-triage`).
|
||||
- **`pending`** = needs human judgment. Either manually created or from a legacy review path.
|
||||
|
||||
This makes auto-resolve safe by design: the quality gate is upstream (in the review), not at the resolve boundary.
|
||||
|
||||
## Prevention Strategies
|
||||
|
||||
### Make State Transitions Load-Bearing, Not Advisory
|
||||
|
||||
If a state field exists, at least one downstream consumer must branch on it. If nothing branches on the value, the field is dead metadata.
|
||||
|
||||
- **Gate on state at consumption boundaries.** Any skill that reads todos must partition by status before processing.
|
||||
- **Require explicit skip-and-report.** Silent skipping is indistinguishable from silent acceptance. When a skill filters by state, it reports what it filtered out.
|
||||
- **Default-deny for new statuses.** If a new status value is added, existing consumers should skip unknown statuses rather than process everything.
|
||||
|
||||
### Dead-Metadata Detection
|
||||
|
||||
When reviewing a skill that defines a state field, ask: "What would change if this field were always the same value?" If the answer is "nothing," the field is dead metadata and either needs enforcement or removal. This is the exact scenario that produced the original issue.
|
||||
|
||||
### Producer Declares Consumer Expectations
|
||||
|
||||
When a skill creates artifacts for downstream consumption, it should state which downstream skill processes them and what state precondition that skill requires. The inverse should also hold: consuming skills should state what upstream flows produce items in the expected state.
|
||||
|
||||
## Cross-References
|
||||
|
||||
- [review-skill-promotion-orchestration-contract.md](../skill-design/review-skill-promotion-orchestration-contract.md) -- promotion hazard: if mode flags are dropped during promotion, the wrong artifacts are produced upstream
|
||||
- [compound-refresh-skill-improvements.md](../skill-design/compound-refresh-skill-improvements.md) -- "conservative confidence in autonomous mode" principle that motivates status enforcement
|
||||
- [claude-permissions-optimizer-classification-fix.md](../skill-design/claude-permissions-optimizer-classification-fix.md) -- "pipeline ordering is an architectural invariant" pattern; the same concept applies to the review -> triage -> resolve pipeline
|
||||
@@ -116,8 +116,8 @@ Core workflow commands use `ce:` prefix to unambiguously identify them as compou
|
||||
| `/report-bug-ce` | Report a bug in the compound-engineering plugin |
|
||||
| `/reproduce-bug` | Reproduce bugs using logs and console |
|
||||
| `/resolve-pr-parallel` | Resolve PR comments in parallel |
|
||||
| `/resolve-todo-parallel` | Resolve todos in parallel |
|
||||
| `/triage` | Triage and prioritize issues |
|
||||
| `/todo-resolve` | Resolve todos in parallel |
|
||||
| `/todo-triage` | Triage and prioritize pending todos |
|
||||
| `/test-browser` | Run browser tests on PR-affected pages |
|
||||
| `/test-xcode` | Build and test iOS apps on simulator |
|
||||
| `/feature-video` | Record video walkthroughs and add to PR description |
|
||||
@@ -147,7 +147,7 @@ Core workflow commands use `ce:` prefix to unambiguously identify them as compou
|
||||
|-------|-------------|
|
||||
| `document-review` | Review documents using parallel persona agents for role-specific feedback |
|
||||
| `every-style-editor` | Review copy for Every's style guide compliance |
|
||||
| `file-todos` | File-based todo tracking system |
|
||||
| `todo-create` | File-based todo tracking system |
|
||||
| `git-worktree` | Manage Git worktrees for parallel development |
|
||||
| `proof` | Create, edit, and share documents via Proof collaborative editor |
|
||||
| `claude-permissions-optimizer` | Optimize Claude Code permissions from session history |
|
||||
|
||||
@@ -32,7 +32,7 @@ Check `$ARGUMENTS` for `mode:autonomous` or `mode:report-only`. If either token
|
||||
- **Skip all user questions.** Never pause for approval or clarification once scope has been established.
|
||||
- **Apply only `safe_auto -> review-fixer` findings.** Leave `gated_auto`, `manual`, `human`, and `release` work unresolved.
|
||||
- **Write a run artifact** under `.context/compound-engineering/ce-review-beta/<run-id>/` summarizing findings, applied fixes, residual actionable work, and advisory outputs.
|
||||
- **Create durable todo files only for unresolved actionable findings** whose final owner is `downstream-resolver`. Load the `file-todos` skill for the canonical directory path and naming convention.
|
||||
- **Create durable todo files only for unresolved actionable findings** whose final owner is `downstream-resolver`. Load the `todo-create` skill for the canonical directory path and naming convention.
|
||||
- **Never commit, push, or create a PR** from autonomous mode. Parent workflows own those decisions.
|
||||
|
||||
### Report-only mode rules
|
||||
@@ -476,7 +476,7 @@ After presenting findings and verdict (Stage 6), route the next steps by mode. R
|
||||
- applied fixes
|
||||
- residual actionable work
|
||||
- advisory-only outputs
|
||||
- In autonomous mode, create durable todo files only for unresolved actionable findings whose final owner is `downstream-resolver`. Load the `file-todos` skill for the canonical directory path, naming convention, YAML frontmatter structure, and template. Each todo should map the finding's severity to the todo priority (`P0`/`P1` -> `p1`, `P2` -> `p2`, `P3` -> `p3`) and set `status: ready` since these findings have already been triaged by synthesis.
|
||||
- In autonomous mode, create durable todo files only for unresolved actionable findings whose final owner is `downstream-resolver`. Load the `todo-create` skill for the canonical directory path, naming convention, YAML frontmatter structure, and template. Each todo should map the finding's severity to the todo priority (`P0`/`P1` -> `p1`, `P2` -> `p2`, `P3` -> `p3`) and set `status: ready` since these findings have already been triaged by synthesis.
|
||||
- Do not create todos for `advisory` findings, `owner: human`, `owner: release`, or protected-artifact cleanup suggestions.
|
||||
- If only advisory outputs remain, create no todos.
|
||||
- Interactive mode may offer to externalize residual actionable work after fixes, but it is not required to finish the review.
|
||||
|
||||
@@ -239,9 +239,9 @@ Complete system context map with component interactions
|
||||
|
||||
Run the Task compound-engineering:review:code-simplicity-reviewer() to see if we can simplify the code.
|
||||
|
||||
### 5. Findings Synthesis and Todo Creation Using file-todos Skill
|
||||
### 5. Findings Synthesis and Todo Creation Using todo-create Skill
|
||||
|
||||
<critical_requirement> ALL findings MUST be stored as todo files using the file-todos skill. Load the `file-todos` skill for the canonical directory path, naming convention, and template. Create todo files immediately after synthesis - do NOT present findings for user approval first. </critical_requirement>
|
||||
<critical_requirement> ALL findings MUST be stored as todo files using the todo-create skill. Load the `todo-create` skill for the canonical directory path, naming convention, and template. Create todo files immediately after synthesis - do NOT present findings for user approval first. </critical_requirement>
|
||||
|
||||
#### Step 1: Synthesize All Findings
|
||||
|
||||
@@ -262,9 +262,9 @@ Remove duplicates, prioritize by severity and impact.
|
||||
|
||||
</synthesis_tasks>
|
||||
|
||||
#### Step 2: Create Todo Files Using file-todos Skill
|
||||
#### Step 2: Create Todo Files Using todo-create Skill
|
||||
|
||||
<critical_instruction> Use the file-todos skill to create todo files for ALL findings immediately. Do NOT present findings one-by-one asking for user approval. Create all todo files in parallel using the skill, then summarize results to user. </critical_instruction>
|
||||
<critical_instruction> Use the todo-create skill to create todo files for ALL findings immediately. Do NOT present findings one-by-one asking for user approval. Create all todo files in parallel using the skill, then summarize results to user. </critical_instruction>
|
||||
|
||||
**Implementation Options:**
|
||||
|
||||
@@ -272,7 +272,7 @@ Remove duplicates, prioritize by severity and impact.
|
||||
|
||||
- Create todo files directly using Write tool
|
||||
- All findings in parallel for speed
|
||||
- Use standard template from the `file-todos` skill's [todo-template.md](../file-todos/assets/todo-template.md)
|
||||
- Use standard template from the `todo-create` skill's [todo-template.md](../todo-create/assets/todo-template.md)
|
||||
- Follow naming convention: `{issue_id}-pending-{priority}-{description}.md`
|
||||
|
||||
**Option B: Sub-Agents in Parallel (Recommended for Scale)** For large PRs with 15+ findings, use sub-agents to create finding files in parallel:
|
||||
@@ -299,10 +299,10 @@ Sub-agents can:
|
||||
1. Synthesize all findings into categories (P1/P2/P3)
|
||||
2. Group findings by severity
|
||||
3. Launch 3 parallel sub-agents (one per severity level)
|
||||
4. Each sub-agent creates its batch of todos using the file-todos skill
|
||||
4. Each sub-agent creates its batch of todos using the todo-create skill
|
||||
5. Consolidate results and present summary
|
||||
|
||||
**Process (Using file-todos Skill):**
|
||||
**Process (Using todo-create Skill):**
|
||||
|
||||
1. For each finding:
|
||||
|
||||
@@ -312,15 +312,15 @@ Sub-agents can:
|
||||
- Estimate effort (Small/Medium/Large)
|
||||
- Add acceptance criteria and work log
|
||||
|
||||
2. Use file-todos skill for structured todo management:
|
||||
2. Use todo-create skill for structured todo management:
|
||||
|
||||
```bash
|
||||
skill: file-todos
|
||||
skill: todo-create
|
||||
```
|
||||
|
||||
The skill provides:
|
||||
|
||||
- Template location: the `file-todos` skill's [todo-template.md](../file-todos/assets/todo-template.md)
|
||||
- Template location: the `todo-create` skill's [todo-template.md](../todo-create/assets/todo-template.md)
|
||||
- Naming convention: `{issue_id}-{status}-{priority}-{description}.md`
|
||||
- YAML frontmatter structure: status, priority, issue_id, tags, dependencies
|
||||
- All required sections: Problem Statement, Findings, Solutions, etc.
|
||||
@@ -340,7 +340,7 @@ Sub-agents can:
|
||||
004-pending-p3-unused-parameter.md
|
||||
```
|
||||
|
||||
5. Follow template structure from file-todos skill: the `file-todos` skill's [todo-template.md](../file-todos/assets/todo-template.md)
|
||||
5. Follow template structure from todo-create skill: the `todo-create` skill's [todo-template.md](../todo-create/assets/todo-template.md)
|
||||
|
||||
**Todo File Structure (from template):**
|
||||
|
||||
@@ -433,13 +433,13 @@ After creating all todo files, present comprehensive summary:
|
||||
2. **Triage All Todos**:
|
||||
```bash
|
||||
ls .context/compound-engineering/todos/*-pending-*.md todos/*-pending-*.md 2>/dev/null # View all pending todos
|
||||
/triage # Use slash command for interactive triage
|
||||
/todo-triage # Use slash command for interactive triage
|
||||
```
|
||||
|
||||
3. **Work on Approved Todos**:
|
||||
|
||||
```bash
|
||||
/resolve-todo-parallel # Fix all approved items efficiently
|
||||
/todo-resolve # Fix all approved items efficiently
|
||||
```
|
||||
|
||||
4. **Track Progress**:
|
||||
|
||||
@@ -1,230 +0,0 @@
|
||||
---
|
||||
name: file-todos
|
||||
description: This skill should be used when managing the file-based todo tracking system in the .context/compound-engineering/todos/ directory. It provides workflows for creating todos, managing status and dependencies, conducting triage, and integrating with code review processes.
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
# File-Based Todo Tracking Skill
|
||||
|
||||
## Overview
|
||||
|
||||
The `.context/compound-engineering/todos/` directory contains a file-based tracking system for managing code review feedback, technical debt, feature requests, and work items. Each todo is a markdown file with YAML frontmatter and structured sections.
|
||||
|
||||
> **Legacy support:** During the transition period, always check both `.context/compound-engineering/todos/` (canonical) and `todos/` (legacy) when reading or searching for todos. Write new todos only to the canonical path. Unlike per-run scratch directories, `.context/compound-engineering/todos/` has a multi-session lifecycle -- do not clean it up as part of post-run scratch cleanup.
|
||||
|
||||
This skill should be used when:
|
||||
- Creating new todos from findings or feedback
|
||||
- Managing todo lifecycle (pending -> ready -> complete)
|
||||
- Triaging pending items for approval
|
||||
- Checking or managing dependencies
|
||||
- Converting PR comments or code findings into tracked work
|
||||
- Updating work logs during todo execution
|
||||
|
||||
## Directory Paths
|
||||
|
||||
| Purpose | Path |
|
||||
|---------|------|
|
||||
| **Canonical (write here)** | `.context/compound-engineering/todos/` |
|
||||
| **Legacy (read-only)** | `todos/` |
|
||||
|
||||
When searching or listing todos, always search both paths. When creating new todos, always write to the canonical path.
|
||||
|
||||
## File Naming Convention
|
||||
|
||||
```
|
||||
{issue_id}-{status}-{priority}-{description}.md
|
||||
```
|
||||
|
||||
**Components:**
|
||||
- **issue_id**: Sequential number (001, 002, 003...) -- never reused
|
||||
- **status**: `pending` (needs triage), `ready` (approved), `complete` (done)
|
||||
- **priority**: `p1` (critical), `p2` (important), `p3` (nice-to-have)
|
||||
- **description**: kebab-case, brief description
|
||||
|
||||
**Examples:**
|
||||
```
|
||||
001-pending-p1-mailer-test.md
|
||||
002-ready-p1-fix-n-plus-1.md
|
||||
005-complete-p2-refactor-csv.md
|
||||
```
|
||||
|
||||
## File Structure
|
||||
|
||||
Each todo is a markdown file with YAML frontmatter and structured sections. Use the template at [todo-template.md](./assets/todo-template.md) as a starting point when creating new todos.
|
||||
|
||||
**Required sections:**
|
||||
- **Problem Statement** -- What is broken, missing, or needs improvement?
|
||||
- **Findings** -- Investigation results, root cause, key discoveries
|
||||
- **Proposed Solutions** -- Multiple options with pros/cons, effort, risk
|
||||
- **Recommended Action** -- Clear plan (filled during triage)
|
||||
- **Acceptance Criteria** -- Testable checklist items
|
||||
- **Work Log** -- Chronological record with date, actions, learnings
|
||||
|
||||
**Optional sections:**
|
||||
- **Technical Details** -- Affected files, related components, DB changes
|
||||
- **Resources** -- Links to errors, tests, PRs, documentation
|
||||
- **Notes** -- Additional context or decisions
|
||||
|
||||
**YAML frontmatter fields:**
|
||||
```yaml
|
||||
---
|
||||
status: ready # pending | ready | complete
|
||||
priority: p1 # p1 | p2 | p3
|
||||
issue_id: "002"
|
||||
tags: [rails, performance, database]
|
||||
dependencies: ["001"] # Issue IDs this is blocked by
|
||||
---
|
||||
```
|
||||
|
||||
## Common Workflows
|
||||
|
||||
> **Tool preference:** Use native file-search (e.g., Glob in Claude Code) and content-search (e.g., Grep in Claude Code) tools instead of shell commands for finding and reading todo files. This avoids unnecessary permission prompts in sub-agent workflows. Use shell only for operations that have no native equivalent (e.g., `mv` for renames, `mkdir -p` for directory creation).
|
||||
|
||||
### Creating a New Todo
|
||||
|
||||
1. Ensure directory exists: `mkdir -p .context/compound-engineering/todos/`
|
||||
2. Determine next issue ID by searching both canonical and legacy paths for files matching `[0-9]*-*.md` using the native file-search/glob tool. Extract the numeric prefix from each filename, find the highest, and increment by one. Zero-pad to 3 digits (e.g., `007`).
|
||||
3. Read the template at [todo-template.md](./assets/todo-template.md), then write it to `.context/compound-engineering/todos/{NEXT_ID}-pending-{priority}-{description}.md` using the native file-write tool.
|
||||
4. Edit and fill required sections:
|
||||
- Problem Statement
|
||||
- Findings (if from investigation)
|
||||
- Proposed Solutions (multiple options)
|
||||
- Acceptance Criteria
|
||||
- Add initial Work Log entry
|
||||
5. Determine status: `pending` (needs triage) or `ready` (pre-approved)
|
||||
6. Add relevant tags for filtering
|
||||
|
||||
**When to create a todo:**
|
||||
- Requires more than 15-20 minutes of work
|
||||
- Needs research, planning, or multiple approaches considered
|
||||
- Has dependencies on other work
|
||||
- Requires manager approval or prioritization
|
||||
- Part of larger feature or refactor
|
||||
- Technical debt needing documentation
|
||||
|
||||
**When to act immediately instead:**
|
||||
- Issue is trivial (< 15 minutes)
|
||||
- Complete context available now
|
||||
- No planning needed
|
||||
- User explicitly requests immediate action
|
||||
- Simple bug fix with obvious solution
|
||||
|
||||
### Triaging Pending Items
|
||||
|
||||
1. Find pending items using the native file-search/glob tool with pattern `*-pending-*.md` in both directory paths.
|
||||
2. For each todo:
|
||||
- Read Problem Statement and Findings
|
||||
- Review Proposed Solutions
|
||||
- Make decision: approve, defer, or modify priority
|
||||
3. Update approved todos:
|
||||
- Rename file: `mv {file}-pending-{pri}-{desc}.md {file}-ready-{pri}-{desc}.md`
|
||||
- Update frontmatter: `status: pending` -> `status: ready`
|
||||
- Fill "Recommended Action" section with clear plan
|
||||
- Adjust priority if different from initial assessment
|
||||
4. Deferred todos stay in `pending` status
|
||||
|
||||
Load the `triage` skill for an interactive approval workflow.
|
||||
|
||||
### Managing Dependencies
|
||||
|
||||
**To track dependencies:**
|
||||
|
||||
```yaml
|
||||
dependencies: ["002", "005"] # This todo blocked by issues 002 and 005
|
||||
dependencies: [] # No blockers - can work immediately
|
||||
```
|
||||
|
||||
**To check what blocks a todo:** Use the native content-search tool (e.g., Grep in Claude Code) to search for `^dependencies:` in the todo file.
|
||||
|
||||
**To find what a todo blocks:** Search both directory paths for files containing `dependencies:.*"002"` using the native content-search tool.
|
||||
|
||||
**To verify blockers are complete before starting:** For each dependency ID, use the native file-search/glob tool to look for `{dep_id}-complete-*.md` in both directory paths. Any missing matches indicate incomplete blockers.
|
||||
|
||||
### Updating Work Logs
|
||||
|
||||
When working on a todo, always add a work log entry:
|
||||
|
||||
```markdown
|
||||
### YYYY-MM-DD - Session Title
|
||||
|
||||
**By:** Agent name / Developer Name
|
||||
|
||||
**Actions:**
|
||||
- Specific changes made (include file:line references)
|
||||
- Commands executed
|
||||
- Tests run
|
||||
- Results of investigation
|
||||
|
||||
**Learnings:**
|
||||
- What worked / what didn't
|
||||
- Patterns discovered
|
||||
- Key insights for future work
|
||||
```
|
||||
|
||||
Work logs serve as:
|
||||
- Historical record of investigation
|
||||
- Documentation of approaches attempted
|
||||
- Knowledge sharing for team
|
||||
- Context for future similar work
|
||||
|
||||
### Completing a Todo
|
||||
|
||||
1. Verify all acceptance criteria checked off
|
||||
2. Update Work Log with final session and results
|
||||
3. Rename file: `mv {file}-ready-{pri}-{desc}.md {file}-complete-{pri}-{desc}.md`
|
||||
4. Update frontmatter: `status: ready` -> `status: complete`
|
||||
5. Check for unblocked work: search both directory paths for `*-ready-*.md` files containing `dependencies:.*"{issue_id}"` using the native content-search tool
|
||||
6. Commit with issue reference: `feat: resolve issue 002`
|
||||
|
||||
## Integration with Development Workflows
|
||||
|
||||
| Trigger | Flow | Tool |
|
||||
|---------|------|------|
|
||||
| Code review | `/ce:review` -> Findings -> `/triage` -> Todos | Review agent + skill |
|
||||
| Beta autonomous review | `/ce:review-beta mode:autonomous` -> Downstream-resolver residual todos -> `/resolve-todo-parallel` | Review skill + todos |
|
||||
| PR comments | `/resolve_pr_parallel` -> Individual fixes -> Todos | gh CLI + skill |
|
||||
| Code TODOs | `/resolve-todo-parallel` -> Fixes + Complex todos | Agent + skill |
|
||||
| Planning | Brainstorm -> Create todo -> Work -> Complete | Skill |
|
||||
| Feedback | Discussion -> Create todo -> Triage -> Work | Skill |
|
||||
|
||||
## Quick Reference Patterns
|
||||
|
||||
Use the native file-search/glob tool (e.g., Glob in Claude Code) and content-search tool (e.g., Grep in Claude Code) for these operations. Search both canonical and legacy directory paths.
|
||||
|
||||
**Finding work:**
|
||||
|
||||
| Goal | Tool | Pattern |
|
||||
|------|------|---------|
|
||||
| List highest priority unblocked work | Content-search | `dependencies: \[\]` in `*-ready-p1-*.md` |
|
||||
| List all pending items needing triage | File-search | `*-pending-*.md` |
|
||||
| Find next issue ID | File-search | `[0-9]*-*.md`, extract highest numeric prefix |
|
||||
| Count by status | File-search | `*-pending-*.md`, `*-ready-*.md`, `*-complete-*.md` |
|
||||
|
||||
**Dependency management:**
|
||||
|
||||
| Goal | Tool | Pattern |
|
||||
|------|------|---------|
|
||||
| What blocks this todo? | Content-search | `^dependencies:` in the specific todo file |
|
||||
| What does this todo block? | Content-search | `dependencies:.*"{id}"` across all todo files |
|
||||
|
||||
**Searching:**
|
||||
|
||||
| Goal | Tool | Pattern |
|
||||
|------|------|---------|
|
||||
| Search by tag | Content-search | `tags:.*{tag}` across all todo files |
|
||||
| Search by priority | File-search | `*-p1-*.md` (or p2, p3) |
|
||||
| Full-text search | Content-search | `{keyword}` across both directory paths |
|
||||
|
||||
## Key Distinctions
|
||||
|
||||
**File-todos system (this skill):**
|
||||
- Markdown files in `.context/compound-engineering/todos/` (legacy: `todos/`)
|
||||
- Development/project tracking across sessions and agents
|
||||
- Standalone markdown files with YAML frontmatter
|
||||
- Persisted to disk, cross-agent accessible
|
||||
|
||||
**In-session task tracking (e.g., TaskCreate/TaskUpdate in Claude Code, update_plan in Codex):**
|
||||
- In-memory task tracking during agent sessions
|
||||
- Temporary tracking for single conversation
|
||||
- Not persisted to disk after session ends
|
||||
- Different purpose: use for tracking steps within a session, not for durable cross-session work items
|
||||
@@ -25,7 +25,7 @@ CRITICAL: You MUST execute every step below IN ORDER. Do NOT skip any required s
|
||||
|
||||
5. `/ce:review`
|
||||
|
||||
6. `/compound-engineering:resolve-todo-parallel`
|
||||
6. `/compound-engineering:todo-resolve`
|
||||
|
||||
7. `/compound-engineering:test-browser`
|
||||
|
||||
|
||||
@@ -1,67 +0,0 @@
|
||||
---
|
||||
name: resolve-todo-parallel
|
||||
description: Resolve all pending CLI todos using parallel processing, compound on lessons learned, then clean up completed todos.
|
||||
argument-hint: "[optional: specific todo ID or pattern]"
|
||||
---
|
||||
|
||||
Resolve all TODO comments using parallel processing, document lessons learned, then clean up completed todos.
|
||||
|
||||
## Workflow
|
||||
|
||||
### 1. Analyze
|
||||
|
||||
Get all unresolved TODOs from `.context/compound-engineering/todos/*.md` and legacy `todos/*.md`
|
||||
|
||||
Residual actionable work may come from `ce:review-beta mode:autonomous` after its in-skill `safe_auto` pass. Treat those todos as normal unresolved work items; the review skill has already decided they should not be auto-fixed inline.
|
||||
|
||||
If any todo recommends deleting, removing, or gitignoring files in `docs/brainstorms/`, `docs/plans/`, or `docs/solutions/`, skip it and mark it as `wont_fix`. These are compound-engineering pipeline artifacts that are intentional and permanent.
|
||||
|
||||
### 2. Plan
|
||||
|
||||
Create a task list of all unresolved items grouped by type (e.g., `TaskCreate` in Claude Code, `update_plan` in Codex). Analyze dependencies and prioritize items that others depend on. For example, if a rename is needed, it must complete before dependent items. Output a mermaid flow diagram showing execution order — what can run in parallel, and what must run first.
|
||||
|
||||
### 3. Implement (PARALLEL)
|
||||
|
||||
Spawn a `compound-engineering:workflow:pr-comment-resolver` agent for each unresolved item.
|
||||
|
||||
If there are 3 items, spawn 3 agents — one per item. Prefer running all agents in parallel; if the platform does not support parallel dispatch, run them sequentially respecting the dependency order from step 2.
|
||||
|
||||
Keep parent-context pressure bounded:
|
||||
- If there are 1-4 unresolved items, direct parallel returns are fine
|
||||
- If there are 5+ unresolved items, launch in batches of at most 4 agents at a time
|
||||
- Require each resolver agent to return only a short status summary to the parent: todo handled, files changed, tests run or skipped, and any blocker that still needs follow-up
|
||||
|
||||
If the todo set is large enough that even batched short returns are likely to get noisy, use a per-run scratch directory such as `.context/compound-engineering/resolve-todo-parallel/<run-id>/`:
|
||||
- Have each resolver write a compact artifact for its todo there
|
||||
- Return only a completion summary to the parent
|
||||
- Re-read only the artifacts that are needed to summarize outcomes, document learnings, or decide whether a todo is truly resolved
|
||||
|
||||
### 4. Commit & Resolve
|
||||
|
||||
- Commit changes
|
||||
- Remove the TODO from the file, and mark it as resolved.
|
||||
- Push to remote
|
||||
|
||||
GATE: STOP. Verify that todos have been resolved and changes committed. Do NOT proceed to step 5 if no todos were resolved.
|
||||
|
||||
### 5. Compound on Lessons Learned
|
||||
|
||||
Load the `ce:compound` skill to document what was learned from resolving the todos.
|
||||
|
||||
The todo resolutions often surface patterns, recurring issues, or architectural insights worth capturing. This step ensures that knowledge compounds rather than being lost.
|
||||
|
||||
GATE: STOP. Verify that the compound skill produced a solution document in `docs/solutions/`. If no document was created (user declined or no non-trivial learnings), continue to step 6.
|
||||
|
||||
### 6. Clean Up Completed Todos
|
||||
|
||||
Search both `.context/compound-engineering/todos/` and legacy `todos/` for files with `done`, `resolved`, or `complete` status, then delete them to keep the todo list clean and actionable.
|
||||
|
||||
If a per-run scratch directory was created at `.context/compound-engineering/resolve-todo-parallel/<run-id>/`, and the user did not ask to inspect it, delete that specific `<run-id>/` directory after todo cleanup succeeds. Do not delete any other `.context/` subdirectories.
|
||||
|
||||
After cleanup, output a summary:
|
||||
|
||||
```
|
||||
Todos resolved: [count]
|
||||
Lessons documented: [path to solution doc, or "skipped"]
|
||||
Todos cleaned up: [count deleted]
|
||||
```
|
||||
@@ -28,7 +28,7 @@ Wait for both to complete before continuing.
|
||||
|
||||
## Finalize Phase
|
||||
|
||||
7. `/compound-engineering:resolve-todo-parallel` — resolve findings, compound on learnings, clean up completed todos
|
||||
7. `/compound-engineering:todo-resolve` — resolve findings, compound on learnings, clean up completed todos
|
||||
8. `/compound-engineering:feature-video` — record the final walkthrough and add to PR
|
||||
9. Output `<promise>DONE</promise>` when video is in PR
|
||||
|
||||
|
||||
@@ -225,12 +225,12 @@ When a test fails:
|
||||
|
||||
How to proceed?
|
||||
1. Fix now - I'll help debug and fix
|
||||
2. Create todo - Add a todo for later (using the file-todos skill)
|
||||
2. Create todo - Add a todo for later (using the todo-create skill)
|
||||
3. Skip - Continue testing other pages
|
||||
```
|
||||
|
||||
3. **If "Fix now":** investigate, propose a fix, apply, re-run the failing test
|
||||
4. **If "Create todo":** load the `file-todos` skill and create a todo with priority p1 and description `browser-test-{description}`, continue
|
||||
4. **If "Create todo":** load the `todo-create` skill and create a todo with priority p1 and description `browser-test-{description}`, continue
|
||||
5. **If "Skip":** log as skipped, continue
|
||||
|
||||
### 10. Test Summary
|
||||
|
||||
@@ -139,12 +139,12 @@ When a test fails:
|
||||
|
||||
How to proceed?
|
||||
1. Fix now - I'll help debug and fix
|
||||
2. Create todo - Add a todo for later (using the file-todos skill)
|
||||
2. Create todo - Add a todo for later (using the todo-create skill)
|
||||
3. Skip - Continue testing other screens
|
||||
```
|
||||
|
||||
3. **If "Fix now":** investigate, propose a fix, rebuild and retest
|
||||
4. **If "Create todo":** load the `file-todos` skill and create a todo with priority p1 and description `xcode-{description}`, continue
|
||||
4. **If "Create todo":** load the `todo-create` skill and create a todo with priority p1 and description `xcode-{description}`, continue
|
||||
5. **If "Skip":** log as skipped, continue
|
||||
|
||||
### 8. Test Summary
|
||||
|
||||
103
plugins/compound-engineering/skills/todo-create/SKILL.md
Normal file
103
plugins/compound-engineering/skills/todo-create/SKILL.md
Normal file
@@ -0,0 +1,103 @@
|
||||
---
|
||||
name: todo-create
|
||||
description: Use when creating durable work items, managing todo lifecycle, or tracking findings across sessions in the file-based todo system
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
# File-Based Todo Tracking
|
||||
|
||||
## Overview
|
||||
|
||||
The `.context/compound-engineering/todos/` directory is a file-based tracking system for code review feedback, technical debt, feature requests, and work items. Each todo is a markdown file with YAML frontmatter.
|
||||
|
||||
> **Legacy support:** Always check both `.context/compound-engineering/todos/` (canonical) and `todos/` (legacy) when reading. Write new todos only to the canonical path. This directory has a multi-session lifecycle -- do not clean it up as scratch.
|
||||
|
||||
## Directory Paths
|
||||
|
||||
| Purpose | Path |
|
||||
|---------|------|
|
||||
| **Canonical (write here)** | `.context/compound-engineering/todos/` |
|
||||
| **Legacy (read-only)** | `todos/` |
|
||||
|
||||
## File Naming Convention
|
||||
|
||||
```
|
||||
{issue_id}-{status}-{priority}-{description}.md
|
||||
```
|
||||
|
||||
- **issue_id**: Sequential number (001, 002, ...) -- never reused
|
||||
- **status**: `pending` | `ready` | `complete`
|
||||
- **priority**: `p1` (critical) | `p2` (important) | `p3` (nice-to-have)
|
||||
- **description**: kebab-case, brief
|
||||
|
||||
**Example:** `002-ready-p1-fix-n-plus-1.md`
|
||||
|
||||
## File Structure
|
||||
|
||||
Each todo has YAML frontmatter and structured sections. Use the template at [todo-template.md](./assets/todo-template.md) when creating new todos.
|
||||
|
||||
```yaml
|
||||
---
|
||||
status: ready
|
||||
priority: p1
|
||||
issue_id: "002"
|
||||
tags: [rails, performance]
|
||||
dependencies: ["001"] # Issue IDs this is blocked by
|
||||
---
|
||||
```
|
||||
|
||||
**Required sections:** Problem Statement, Findings, Proposed Solutions, Recommended Action (filled during triage), Acceptance Criteria, Work Log.
|
||||
|
||||
**Optional sections:** Technical Details, Resources, Notes.
|
||||
|
||||
## Workflows
|
||||
|
||||
> **Tool preference:** Use native file-search/glob and content-search tools instead of shell commands for finding and reading todo files. Shell only for operations with no native equivalent (`mv`, `mkdir -p`).
|
||||
|
||||
### Creating a New Todo
|
||||
|
||||
1. `mkdir -p .context/compound-engineering/todos/`
|
||||
2. Search both paths for `[0-9]*-*.md`, find the highest numeric prefix, increment, zero-pad to 3 digits.
|
||||
3. Read [todo-template.md](./assets/todo-template.md), write to canonical path as `{NEXT_ID}-pending-{priority}-{description}.md`.
|
||||
4. Fill Problem Statement, Findings, Proposed Solutions, Acceptance Criteria, and initial Work Log entry.
|
||||
5. Set status: `pending` (needs triage) or `ready` (pre-approved).
|
||||
|
||||
**Create a todo when** the work needs more than ~15 minutes, has dependencies, requires planning, or needs prioritization. **Act immediately instead** when the fix is trivial, obvious, and self-contained.
|
||||
|
||||
### Triaging Pending Items
|
||||
|
||||
1. Glob `*-pending-*.md` in both paths.
|
||||
2. Review each todo's Problem Statement, Findings, and Proposed Solutions.
|
||||
3. Approve: rename `pending` -> `ready` in filename and frontmatter, fill Recommended Action.
|
||||
4. Defer: leave as `pending`.
|
||||
|
||||
Load the `todo-triage` skill for an interactive approval workflow.
|
||||
|
||||
### Managing Dependencies
|
||||
|
||||
```yaml
|
||||
dependencies: ["002", "005"] # Blocked by these issues
|
||||
dependencies: [] # No blockers
|
||||
```
|
||||
|
||||
To check blockers: search for `{dep_id}-complete-*.md` in both paths. Missing matches = incomplete blockers.
|
||||
|
||||
### Completing a Todo
|
||||
|
||||
1. Verify all acceptance criteria.
|
||||
2. Update Work Log with final session.
|
||||
3. Rename `ready` -> `complete` in filename and frontmatter.
|
||||
4. Check for unblocked work: search for files containing `dependencies:.*"{issue_id}"`.
|
||||
|
||||
## Integration with Workflows
|
||||
|
||||
| Trigger | Flow |
|
||||
|---------|------|
|
||||
| Code review | `/ce:review` -> Findings -> `/todo-triage` -> Todos |
|
||||
| Autonomous review | `/ce:review-beta mode:autonomous` -> Residual todos -> `/todo-resolve` |
|
||||
| Code TODOs | `/todo-resolve` -> Fixes + Complex todos |
|
||||
| Planning | Brainstorm -> Create todo -> Work -> Complete |
|
||||
|
||||
## Key Distinction
|
||||
|
||||
This skill manages **durable, cross-session work items** persisted as markdown files. For temporary in-session step tracking, use platform task tools (`TaskCreate`/`TaskUpdate` in Claude Code, `update_plan` in Codex) instead.
|
||||
68
plugins/compound-engineering/skills/todo-resolve/SKILL.md
Normal file
68
plugins/compound-engineering/skills/todo-resolve/SKILL.md
Normal file
@@ -0,0 +1,68 @@
|
||||
---
|
||||
name: todo-resolve
|
||||
description: Use when batch-resolving approved todos, especially after code review or triage sessions
|
||||
argument-hint: "[optional: specific todo ID or pattern]"
|
||||
---
|
||||
|
||||
Resolve approved todos using parallel processing, document lessons learned, then clean up.
|
||||
|
||||
Only `ready` todos are resolved. `pending` todos are skipped — they haven't been triaged yet. If pending todos exist, list them at the end so the user knows what was left behind.
|
||||
|
||||
## Workflow
|
||||
|
||||
### 1. Analyze
|
||||
|
||||
Scan `.context/compound-engineering/todos/*.md` and legacy `todos/*.md`. Partition by status:
|
||||
|
||||
- **`ready`** (status field or `-ready-` in filename): resolve these.
|
||||
- **`pending`**: skip. Report them at the end.
|
||||
- **`complete`**: ignore, already done.
|
||||
|
||||
If a specific todo ID or pattern was passed as an argument, filter to matching todos only (still must be `ready`).
|
||||
|
||||
Residual actionable work from `ce:review-beta mode:autonomous` after its `safe_auto` pass will already be `ready`.
|
||||
|
||||
Skip any todo that recommends deleting, removing, or gitignoring files in `docs/brainstorms/`, `docs/plans/`, or `docs/solutions/` — these are intentional pipeline artifacts.
|
||||
|
||||
### 2. Plan
|
||||
|
||||
Create a task list grouped by type (e.g., `TaskCreate` in Claude Code, `update_plan` in Codex). Analyze dependencies -- items that others depend on run first. Output a mermaid diagram showing execution order and parallelism.
|
||||
|
||||
### 3. Implement (PARALLEL)
|
||||
|
||||
Spawn a `compound-engineering:workflow:pr-comment-resolver` agent per item. Prefer parallel; fall back to sequential respecting dependency order.
|
||||
|
||||
**Batching:** 1-4 items: direct parallel returns. 5+ items: batches of 4, each returning only a short status summary (todo handled, files changed, tests run/skipped, blockers).
|
||||
|
||||
For large sets, use a scratch directory at `.context/compound-engineering/todo-resolve/<run-id>/` for per-resolver artifacts. Return only completion summaries to parent.
|
||||
|
||||
### 4. Commit & Resolve
|
||||
|
||||
Commit changes, mark todos resolved, push to remote.
|
||||
|
||||
GATE: STOP. Verify todos resolved and changes committed before proceeding.
|
||||
|
||||
### 5. Compound on Lessons Learned
|
||||
|
||||
Load the `ce:compound` skill to document what was learned. Todo resolutions often surface patterns and architectural insights worth capturing.
|
||||
|
||||
GATE: STOP. Verify the compound skill produced a solution document in `docs/solutions/`. If none (user declined or no learnings), continue.
|
||||
|
||||
### 6. Clean Up
|
||||
|
||||
Delete completed/resolved todo files from both paths. If a scratch directory was created at `.context/compound-engineering/todo-resolve/<run-id>/`, delete it (unless user asked to inspect).
|
||||
|
||||
```
|
||||
Todos resolved: [count]
|
||||
Pending (skipped): [count, or "none"]
|
||||
Lessons documented: [path to solution doc, or "skipped"]
|
||||
Todos cleaned up: [count deleted]
|
||||
```
|
||||
|
||||
If pending todos were skipped, list them:
|
||||
|
||||
```
|
||||
Skipped pending todos (run /todo-triage to approve):
|
||||
- 003-pending-p2-missing-index.md
|
||||
- 005-pending-p3-rename-variable.md
|
||||
```
|
||||
70
plugins/compound-engineering/skills/todo-triage/SKILL.md
Normal file
70
plugins/compound-engineering/skills/todo-triage/SKILL.md
Normal file
@@ -0,0 +1,70 @@
|
||||
---
|
||||
name: todo-triage
|
||||
description: Use when reviewing pending todos for approval, prioritizing code review findings, or interactively categorizing work items
|
||||
argument-hint: "[findings list or source type]"
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
# Todo Triage
|
||||
|
||||
Interactive workflow for reviewing pending todos one by one and deciding whether to approve, skip, or modify each.
|
||||
|
||||
**Do not write code during triage.** This is purely for review and prioritization -- implementation happens in `/todo-resolve`.
|
||||
|
||||
- First set the /model to Haiku
|
||||
- Read all pending todos from `.context/compound-engineering/todos/` and legacy `todos/` directories
|
||||
|
||||
## Workflow
|
||||
|
||||
### 1. Present Each Finding
|
||||
|
||||
For each pending todo, present it clearly with severity, category, description, location, problem scenario, proposed solution, and effort estimate. Then ask:
|
||||
|
||||
```
|
||||
Do you want to add this to the todo list?
|
||||
1. yes - approve and mark ready
|
||||
2. next - skip (deletes the todo file)
|
||||
3. custom - modify before approving
|
||||
```
|
||||
|
||||
Use severity levels: 🔴 P1 (CRITICAL), 🟡 P2 (IMPORTANT), 🔵 P3 (NICE-TO-HAVE).
|
||||
|
||||
Include progress tracking in each header: `Progress: 3/10 completed`
|
||||
|
||||
### 2. Handle Decision
|
||||
|
||||
**yes:** Rename file from `pending` -> `ready` in both filename and frontmatter. Fill the Recommended Action section. If creating a new todo (not updating existing), use the naming convention from the `todo-create` skill.
|
||||
|
||||
Priority mapping: 🔴 P1 -> `p1`, 🟡 P2 -> `p2`, 🔵 P3 -> `p3`
|
||||
|
||||
Confirm: "✅ Approved: `{filename}` (Issue #{issue_id}) - Status: **ready**"
|
||||
|
||||
**next:** Delete the todo file. Log as skipped for the final summary.
|
||||
|
||||
**custom:** Ask what to modify, update, re-present, ask again.
|
||||
|
||||
### 3. Final Summary
|
||||
|
||||
After all items processed:
|
||||
|
||||
```markdown
|
||||
## Triage Complete
|
||||
|
||||
**Total Items:** [X] | **Approved (ready):** [Y] | **Skipped:** [Z]
|
||||
|
||||
### Approved Todos (Ready for Work):
|
||||
- `042-ready-p1-transaction-boundaries.md` - Transaction boundary issue
|
||||
|
||||
### Skipped (Deleted):
|
||||
- Item #5: [reason]
|
||||
```
|
||||
|
||||
### 4. Next Steps
|
||||
|
||||
```markdown
|
||||
What would you like to do next?
|
||||
|
||||
1. run /todo-resolve to resolve the todos
|
||||
2. commit the todos
|
||||
3. nothing, go chill
|
||||
```
|
||||
@@ -1,311 +0,0 @@
|
||||
---
|
||||
name: triage
|
||||
description: Triage and categorize findings for the CLI todo system
|
||||
argument-hint: "[findings list or source type]"
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
- First set the /model to Haiku
|
||||
- Then read all pending todos from `.context/compound-engineering/todos/` and legacy `todos/` directories
|
||||
|
||||
Present all findings, decisions, or issues here one by one for triage. The goal is to go through each item and decide whether to add it to the CLI todo system.
|
||||
|
||||
**IMPORTANT: DO NOT CODE ANYTHING DURING TRIAGE!**
|
||||
|
||||
This command is for:
|
||||
|
||||
- Triaging code review findings
|
||||
- Processing security audit results
|
||||
- Reviewing performance analysis
|
||||
- Handling any other categorized findings that need tracking
|
||||
|
||||
## Workflow
|
||||
|
||||
### Step 1: Present Each Finding
|
||||
|
||||
For each finding, present in this format:
|
||||
|
||||
```
|
||||
---
|
||||
Issue #X: [Brief Title]
|
||||
|
||||
Severity: 🔴 P1 (CRITICAL) / 🟡 P2 (IMPORTANT) / 🔵 P3 (NICE-TO-HAVE)
|
||||
|
||||
Category: [Security/Performance/Architecture/Bug/Feature/etc.]
|
||||
|
||||
Description:
|
||||
[Detailed explanation of the issue or improvement]
|
||||
|
||||
Location: [file_path:line_number]
|
||||
|
||||
Problem Scenario:
|
||||
[Step by step what's wrong or could happen]
|
||||
|
||||
Proposed Solution:
|
||||
[How to fix it]
|
||||
|
||||
Estimated Effort: [Small (< 2 hours) / Medium (2-8 hours) / Large (> 8 hours)]
|
||||
|
||||
---
|
||||
Do you want to add this to the todo list?
|
||||
1. yes - create todo file
|
||||
2. next - skip this item
|
||||
3. custom - modify before creating
|
||||
```
|
||||
|
||||
### Step 2: Handle User Decision
|
||||
|
||||
**When user says "yes":**
|
||||
|
||||
1. **Update existing todo file** (if it exists) or **Create new filename:**
|
||||
|
||||
If todo already exists (from code review):
|
||||
|
||||
- Rename file from `{id}-pending-{priority}-{desc}.md` → `{id}-ready-{priority}-{desc}.md`
|
||||
- Update YAML frontmatter: `status: pending` → `status: ready`
|
||||
- Keep issue_id, priority, and description unchanged
|
||||
|
||||
If creating new todo:
|
||||
|
||||
```
|
||||
{next_id}-ready-{priority}-{brief-description}.md
|
||||
```
|
||||
|
||||
Priority mapping:
|
||||
|
||||
- 🔴 P1 (CRITICAL) → `p1`
|
||||
- 🟡 P2 (IMPORTANT) → `p2`
|
||||
- 🔵 P3 (NICE-TO-HAVE) → `p3`
|
||||
|
||||
Example: `042-ready-p1-transaction-boundaries.md`
|
||||
|
||||
2. **Update YAML frontmatter:**
|
||||
|
||||
```yaml
|
||||
---
|
||||
status: ready # IMPORTANT: Change from "pending" to "ready"
|
||||
priority: p1 # or p2, p3 based on severity
|
||||
issue_id: "042"
|
||||
tags: [category, relevant-tags]
|
||||
dependencies: []
|
||||
---
|
||||
```
|
||||
|
||||
3. **Populate or update the file:**
|
||||
|
||||
```yaml
|
||||
# [Issue Title]
|
||||
|
||||
## Problem Statement
|
||||
[Description from finding]
|
||||
|
||||
## Findings
|
||||
- [Key discoveries]
|
||||
- Location: [file_path:line_number]
|
||||
- [Scenario details]
|
||||
|
||||
## Proposed Solutions
|
||||
|
||||
### Option 1: [Primary solution]
|
||||
- **Pros**: [Benefits]
|
||||
- **Cons**: [Drawbacks if any]
|
||||
- **Effort**: [Small/Medium/Large]
|
||||
- **Risk**: [Low/Medium/High]
|
||||
|
||||
## Recommended Action
|
||||
[Filled during triage - specific action plan]
|
||||
|
||||
## Technical Details
|
||||
- **Affected Files**: [List files]
|
||||
- **Related Components**: [Components affected]
|
||||
- **Database Changes**: [Yes/No - describe if yes]
|
||||
|
||||
## Resources
|
||||
- Original finding: [Source of this issue]
|
||||
- Related issues: [If any]
|
||||
|
||||
## Acceptance Criteria
|
||||
- [ ] [Specific success criteria]
|
||||
- [ ] Tests pass
|
||||
- [ ] Code reviewed
|
||||
|
||||
## Work Log
|
||||
|
||||
### {date} - Approved for Work
|
||||
**By:** Claude Triage System
|
||||
**Actions:**
|
||||
- Issue approved during triage session
|
||||
- Status changed from pending → ready
|
||||
- Ready to be picked up and worked on
|
||||
|
||||
**Learnings:**
|
||||
- [Context and insights]
|
||||
|
||||
## Notes
|
||||
Source: Triage session on {date}
|
||||
```
|
||||
|
||||
4. **Confirm approval:** "✅ Approved: `{new_filename}` (Issue #{issue_id}) - Status: **ready** → Ready to work on"
|
||||
|
||||
**When user says "next":**
|
||||
|
||||
- **Delete the todo file** - Remove it from its current location since it's not relevant
|
||||
- Skip to the next item
|
||||
- Track skipped items for summary
|
||||
|
||||
**When user says "custom":**
|
||||
|
||||
- Ask what to modify (priority, description, details)
|
||||
- Update the information
|
||||
- Present revised version
|
||||
- Ask again: yes/next/custom
|
||||
|
||||
### Step 3: Continue Until All Processed
|
||||
|
||||
- Process all items one by one
|
||||
- Track using TodoWrite for visibility
|
||||
- Don't wait for approval between items - keep moving
|
||||
|
||||
### Step 4: Final Summary
|
||||
|
||||
After all items processed:
|
||||
|
||||
````markdown
|
||||
## Triage Complete
|
||||
|
||||
**Total Items:** [X] **Todos Approved (ready):** [Y] **Skipped:** [Z]
|
||||
|
||||
### Approved Todos (Ready for Work):
|
||||
|
||||
- `042-ready-p1-transaction-boundaries.md` - Transaction boundary issue
|
||||
- `043-ready-p2-cache-optimization.md` - Cache performance improvement ...
|
||||
|
||||
### Skipped Items (Deleted):
|
||||
|
||||
- Item #5: [reason] - Removed
|
||||
- Item #12: [reason] - Removed
|
||||
|
||||
### Summary of Changes Made:
|
||||
|
||||
During triage, the following status updates occurred:
|
||||
|
||||
- **Pending → Ready:** Filenames and frontmatter updated to reflect approved status
|
||||
- **Deleted:** Todo files for skipped findings removed
|
||||
- Each approved file now has `status: ready` in YAML frontmatter
|
||||
|
||||
### Next Steps:
|
||||
|
||||
1. View approved todos ready for work:
|
||||
```bash
|
||||
ls .context/compound-engineering/todos/*-ready-*.md todos/*-ready-*.md 2>/dev/null
|
||||
```
|
||||
````
|
||||
|
||||
2. Start work on approved items:
|
||||
|
||||
```bash
|
||||
/resolve-todo-parallel # Work on multiple approved items efficiently
|
||||
```
|
||||
|
||||
3. Or pick individual items to work on
|
||||
|
||||
4. As you work, update todo status:
|
||||
- Ready → In Progress (in your local context as you work)
|
||||
- In Progress → Complete (rename file: ready → complete, update frontmatter)
|
||||
|
||||
```
|
||||
|
||||
## Example Response Format
|
||||
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
Issue #5: Missing Transaction Boundaries for Multi-Step Operations
|
||||
|
||||
Severity: 🔴 P1 (CRITICAL)
|
||||
|
||||
Category: Data Integrity / Security
|
||||
|
||||
Description: The google_oauth2_connected callback in GoogleOauthCallbacks concern performs multiple database operations without transaction protection. If any step fails midway, the database is left in an inconsistent state.
|
||||
|
||||
Location: app/controllers/concerns/google_oauth_callbacks.rb:13-50
|
||||
|
||||
Problem Scenario:
|
||||
|
||||
1. User.update succeeds (email changed)
|
||||
2. Account.save! fails (validation error)
|
||||
3. Result: User has changed email but no associated Account
|
||||
4. Next login attempt fails completely
|
||||
|
||||
Operations Without Transaction:
|
||||
|
||||
- User confirmation (line 13)
|
||||
- Waitlist removal (line 14)
|
||||
- User profile update (line 21-23)
|
||||
- Account creation (line 28-37)
|
||||
- Avatar attachment (line 39-45)
|
||||
- Journey creation (line 47)
|
||||
|
||||
Proposed Solution: Wrap all operations in ApplicationRecord.transaction do ... end block
|
||||
|
||||
Estimated Effort: Small (30 minutes)
|
||||
|
||||
---
|
||||
|
||||
Do you want to add this to the todo list?
|
||||
|
||||
1. yes - create todo file
|
||||
2. next - skip this item
|
||||
3. custom - modify before creating
|
||||
|
||||
```
|
||||
|
||||
## Important Implementation Details
|
||||
|
||||
### Status Transitions During Triage
|
||||
|
||||
**When "yes" is selected:**
|
||||
1. Rename file: `{id}-pending-{priority}-{desc}.md` → `{id}-ready-{priority}-{desc}.md`
|
||||
2. Update YAML frontmatter: `status: pending` → `status: ready`
|
||||
3. Update Work Log with triage approval entry
|
||||
4. Confirm: "✅ Approved: `{filename}` (Issue #{issue_id}) - Status: **ready**"
|
||||
|
||||
**When "next" is selected:**
|
||||
1. Delete the todo file from its current location
|
||||
2. Skip to next item
|
||||
3. No file remains in the system
|
||||
|
||||
### Progress Tracking
|
||||
|
||||
Every time you present a todo as a header, include:
|
||||
- **Progress:** X/Y completed (e.g., "3/10 completed")
|
||||
- **Estimated time remaining:** Based on how quickly you're progressing
|
||||
- **Pacing:** Monitor time per finding and adjust estimate accordingly
|
||||
|
||||
Example:
|
||||
```
|
||||
|
||||
Progress: 3/10 completed | Estimated time: ~2 minutes remaining
|
||||
|
||||
```
|
||||
|
||||
### Do Not Code During Triage
|
||||
|
||||
- ✅ Present findings
|
||||
- ✅ Make yes/next/custom decisions
|
||||
- ✅ Update todo files (rename, frontmatter, work log)
|
||||
- ❌ Do NOT implement fixes or write code
|
||||
- ❌ Do NOT add detailed implementation details
|
||||
- ❌ That's for /resolve-todo-parallel phase
|
||||
```
|
||||
|
||||
When done give these options
|
||||
|
||||
```markdown
|
||||
What would you like to do next?
|
||||
|
||||
1. run /resolve-todo-parallel to resolve the todos
|
||||
2. commit the todos
|
||||
3. nothing, go chill
|
||||
```
|
||||
@@ -107,8 +107,8 @@ export function transformContentForPi(body: string): string {
|
||||
|
||||
// Claude-specific tool references
|
||||
result = result.replace(/\bAskUserQuestion\b/g, "ask_user_question")
|
||||
result = result.replace(/\bTodoWrite\b/g, "file-based todos (todos/ + /skill:file-todos)")
|
||||
result = result.replace(/\bTodoRead\b/g, "file-based todos (todos/ + /skill:file-todos)")
|
||||
result = result.replace(/\bTodoWrite\b/g, "file-based todos (todos/ + /skill:todo-create)")
|
||||
result = result.replace(/\bTodoRead\b/g, "file-based todos (todos/ + /skill:todo-create)")
|
||||
|
||||
// /command-name or /workflows:command-name -> /workflows-command-name
|
||||
const slashCommandPattern = /(?<![:\w])\/([a-z][a-z0-9_:-]*?)(?=[\s,."')\]}`]|$)/gi
|
||||
|
||||
@@ -20,7 +20,7 @@ Tool mapping:
|
||||
- WebFetch/WebSearch: use curl or Context7 for library docs
|
||||
- AskUserQuestion/Question: present choices as a numbered list in chat and wait for a reply number. For multi-select (multiSelect: true), accept comma-separated numbers. Never skip or auto-configure — always wait for the user's response before proceeding.
|
||||
- Task/Subagent/Parallel: run sequentially in main thread; use multi_tool_use.parallel for tool calls
|
||||
- TodoWrite/TodoRead: use file-based todos in todos/ with file-todos skill
|
||||
- TodoWrite/TodoRead: use file-based todos in todos/ with todo-create skill
|
||||
- Skill: open the referenced SKILL.md and follow it
|
||||
- ExitPlanMode: ignore
|
||||
`
|
||||
|
||||
@@ -82,7 +82,7 @@ describe("convertClaudeToPi", () => {
|
||||
expect(parsedPrompt.body).toContain("ask_user_question")
|
||||
expect(parsedPrompt.body).toContain("/workflows-work")
|
||||
expect(parsedPrompt.body).toContain("/deepen-plan")
|
||||
expect(parsedPrompt.body).toContain("file-based todos (todos/ + /skill:file-todos)")
|
||||
expect(parsedPrompt.body).toContain("file-based todos (todos/ + /skill:todo-create)")
|
||||
})
|
||||
|
||||
test("transforms namespaced Task agent calls using final segment", () => {
|
||||
|
||||
@@ -82,11 +82,11 @@ describe("ce-review-beta contract", () => {
|
||||
expect(schema.properties.findings.items.properties.requires_verification.type).toBe("boolean")
|
||||
expect(schema._meta.confidence_thresholds.suppress).toContain("0.60")
|
||||
|
||||
const fileTodos = await readRepoFile("plugins/compound-engineering/skills/file-todos/SKILL.md")
|
||||
const fileTodos = await readRepoFile("plugins/compound-engineering/skills/todo-create/SKILL.md")
|
||||
expect(fileTodos).toContain("/ce:review-beta mode:autonomous")
|
||||
expect(fileTodos).toContain("/resolve-todo-parallel")
|
||||
expect(fileTodos).toContain("/todo-resolve")
|
||||
|
||||
const resolveTodos = await readRepoFile("plugins/compound-engineering/skills/resolve-todo-parallel/SKILL.md")
|
||||
const resolveTodos = await readRepoFile("plugins/compound-engineering/skills/todo-resolve/SKILL.md")
|
||||
expect(resolveTodos).toContain("ce:review-beta mode:autonomous")
|
||||
expect(resolveTodos).toContain("safe_auto")
|
||||
})
|
||||
|
||||
Reference in New Issue
Block a user