@fro.bot/systematic 2.2.0 → 2.3.0

package/skills/resolve-pr-feedback/SKILL.md

@@ -0,0 +1,374 @@
+---
+name: resolve-pr-feedback
+description: Resolve PR review feedback by evaluating validity and fixing issues in parallel. Use when addressing PR review comments, resolving review threads, or fixing code review feedback.
+argument-hint: "[PR number, comment URL, or blank for current branch's PR]"
+disable-model-invocation: true
+allowed-tools: Bash(gh *), Bash(git *), Read
+---
+
+# Resolve PR Review Feedback
+
+Evaluate and fix PR review feedback, then reply and resolve threads. Spawns parallel agents for each thread.
+
+> **Agent time is cheap. Tech debt is expensive.**
+> Fix everything valid -- including nitpicks and low-priority items. If we're already in the code, fix it rather than punt it.
+
+## Mode Detection
+
+| Argument | Mode |
+|----------|------|
+| No argument | **Full** -- all unresolved threads on the current branch's PR |
+| PR number (e.g., `123`) | **Full** -- all unresolved threads on that PR |
+| Comment/thread URL | **Targeted** -- only that specific thread |
+
+**Targeted mode**: When a URL is provided, ONLY address that feedback. Do not fetch or process other threads.
+
+---
+
+## Full Mode
+
+### 1. Fetch Unresolved Threads
+
+If no PR number was provided, detect from the current branch:
+```bash
+gh pr view --json number -q .number
+```
+
+Then fetch all feedback using the GraphQL script at [scripts/get-pr-comments](scripts/get-pr-comments):
+
+```bash
+bash scripts/get-pr-comments PR_NUMBER
+```
+
+Returns a JSON object with three keys:
+
+| Key | Contents | Has file/line? | Resolvable? |
+|-----|----------|---------------|-------------|
+| `review_threads` | Unresolved, non-outdated inline code review threads | Yes | Yes (GraphQL) |
+| `pr_comments` | Top-level PR conversation comments (excludes PR author) | No | No |
+| `review_bodies` | Review submission bodies with non-empty text (excludes PR author) | No | No |
+
+If the script fails, fall back to:
+```bash
+gh pr view PR_NUMBER --json reviews,comments
+gh api repos/{owner}/{repo}/pulls/PR_NUMBER/comments
+```
+
+### 2. Triage: Separate New from Pending
+
+Before processing, classify each piece of feedback as **new** or **already handled**.
+
+**Review threads**: Read the thread's comments. If there's a substantive reply that acknowledges the concern but defers action (e.g., "need to align on this", "going to think through this", or a reply that presents options without resolving), it's a **pending decision** -- don't re-process. If there's only the original reviewer comment(s) with no substantive response, it's **new**.
+
+**PR comments and review bodies**: These have no resolve mechanism, so they reappear on every run. Apply two filters in order:
+
+1. **Actionability**: Skip items that contain no actionable feedback or questions to answer. Examples: review wrapper text ("Here are some automated review suggestions..."), approvals ("this looks great!"), status badges ("Validated"), CI summaries with no follow-up asks. If there's nothing to fix, answer, or decide, it's not actionable -- drop it from the count entirely.
+2. **Already replied**: For actionable items, check the PR conversation for an existing reply that quotes and addresses the feedback. If a reply already exists, skip. If not, it's new.
+
+The distinction is about content, not who posted what. A deferral from a teammate, a previous skill run, or a manual reply all count. Similarly, actionability is about content -- bot feedback that requests a specific code change is actionable; a bot's boilerplate header wrapping those requests is not.
+
+If there are no new items across all feedback types, skip steps 3-8 and go straight to step 9.
+
+### 3. Cluster Analysis (Gated)
+
+Before planning and dispatching fixes, check whether feedback patterns suggest a systemic issue that warrants broader investigation rather than individual fixes.
+
+**Gate check**: Cluster analysis only runs when at least one signal fires. If neither fires, skip directly to step 4.
+
+| Gate signal | Check |
+|---|---|
+| **Volume** | 3+ new items from triage |
+| **Cross-invocation** | `cross_invocation.signal == true` in the script output (resolved threads exist alongside new ones — evidence of multi-round review) |
+
+If the gate does not fire, proceed to step 4. The common case (first review round with 1-2 comments) skips this step entirely with zero overhead.
+
+**If the gate fires**, analyze feedback for thematic clusters. When the cross-invocation signal fired, include resolved threads from `cross_invocation.resolved_threads` alongside new threads in the analysis — these are previously-resolved threads from earlier review rounds that provide pattern context. Mark them as `previously_resolved` so dispatch (step 5) knows not to individually re-resolve them.
+
+1. **Assign concern categories** from this fixed list: `error-handling`, `validation`, `type-safety`, `naming`, `performance`, `testing`, `security`, `documentation`, `style`, `architecture`, `other`. Each item (new and previously-resolved) gets exactly one category based on what the feedback is about.
+
+2. **Group by category + spatial proximity**. Two items form a potential cluster when they share a concern category AND are spatially proximate (same file, or files in the same directory subtree). Clusters can span new and previously-resolved threads.
+
+   | Thematic match | Spatial proximity | Action |
+   |---|---|---|
+   | Same category | Same file | Cluster |
+   | Same category | Same directory subtree | Cluster |
+   | Same category | Unrelated locations | No cluster |
+   | Different categories | Any | No cluster (same-file grouping still applies for conflict avoidance) |
+
+3. **Synthesize a cluster brief** for each cluster of 2+ items. Pass briefs to agents using a `<cluster-brief>` XML block:
+
+   ```xml
+   <cluster-brief>
+     <theme>[concern category]</theme>
+     <area>[common directory path]</area>
+     <files>[comma-separated file paths]</files>
+     <threads>[comma-separated new thread/comment IDs]</threads>
+     <hypothesis>[one sentence: what the individual comments collectively suggest about a deeper issue]</hypothesis>
+     <prior-resolutions>
+       <thread id="PRRT_..." path="..." category="..."/>
+     </prior-resolutions>
+   </cluster-brief>
+   ```
+
+   The `<prior-resolutions>` element lists previously-resolved threads that clustered with the new threads — their IDs, file paths, and assigned concern categories. This gives the resolver agent the full cross-round picture. When no previously-resolved threads are in the cluster, omit the element.
+
+4. **Items not in any cluster** remain as individual items and are dispatched normally in step 5. Previously-resolved threads that don't cluster with any new thread are dropped — they provided context but no pattern was found.
+
+5. **If no clusters are found** after analysis (the gate fired but items don't form thematic+spatial groups), proceed with all items as individual. The gate was a false positive -- the only cost was the analysis itself.
+
+### 4. Plan
+
+Create a task list of all **new** unresolved items grouped by type (e.g., `todowrite` in OpenCode, `update_plan` in Codex):
+- Code changes requested
+- Questions to answer
+- Style/convention fixes
+- Test additions needed
+
+If step 3 produced clusters, include them in the task list as cluster items alongside individual items.
+
+### 5. Implement (PARALLEL)
+
+Process all three feedback types. Review threads are the primary type; PR comments and review bodies are secondary but should not be ignored.
+
+#### Dispatch boundary for previously-resolved threads
+
+Previously-resolved threads (from `cross_invocation.resolved_threads`) participate in clustering and appear in cluster briefs as `<prior-resolutions>` context. They are NEVER individually dispatched — they were already resolved in prior rounds. Only new threads get individual or cluster dispatch.
+
+#### Individual dispatch (default)
+
+**For review threads** (`review_threads`): Spawn a `systematic:workflow:pr-comment-resolver` agent for each new thread that is NOT already assigned to a cluster from step 3. Clustered threads are handled by cluster dispatch below -- do not dispatch them individually.
+
+Each agent receives:
+- The thread ID
+- The file path and line number
+- The full comment text (all comments in the thread)
+- The PR number (for context)
+- The feedback type (`review_thread`)
+
+**For PR comments and review bodies** (`pr_comments`, `review_bodies`): These lack file/line context. Spawn a `systematic:workflow:pr-comment-resolver` agent for each actionable non-clustered item. The agent receives the comment ID, body text, PR number, and feedback type (`pr_comment` or `review_body`). The agent must identify the relevant files from the comment text and the PR diff.
+
+#### Cluster dispatch
+
+For each cluster identified in step 3, dispatch ONE `systematic:workflow:pr-comment-resolver` agent that receives:
+- The `<cluster-brief>` XML block
+- All thread details for threads in the cluster (IDs, file paths, line numbers, comment text)
+- The PR number
+- The feedback types
+
+The cluster agent reads the broader area before making targeted fixes. It returns one summary per thread it handled (same structure as individual agents), plus a `cluster_assessment` field describing what broader investigation revealed and whether a holistic or individual approach was taken.
+
+#### Agent return format
+
+Each agent returns a short summary:
+- **verdict**: `fixed`, `fixed-differently`, `replied`, `not-addressing`, or `needs-human`
+- **feedback_id**: the thread ID or comment ID it handled
+- **feedback_type**: `review_thread`, `pr_comment`, or `review_body`
+- **reply_text**: the markdown reply to post (quoting the relevant part of the original feedback)
+- **files_changed**: list of files modified (empty if replied/not-addressing)
+- **reason**: brief explanation of what was done or why it was skipped
+
+Cluster agents additionally return:
+- **cluster_assessment**: what the broader investigation found, whether a holistic or individual approach was taken
+
+Verdict meanings:
+- `fixed` -- code change made as requested
+- `fixed-differently` -- code change made, but with a better approach than suggested
+- `replied` -- no code change needed; answered a question, acknowledged feedback, or explained a design decision
+- `not-addressing` -- feedback is factually wrong about the code; skip with evidence
+- `needs-human` -- cannot determine the right action; needs user decision
+
+#### Batching and conflict avoidance
+
+**Batching**: Clusters count as 1 dispatch unit regardless of how many threads they contain. If there are 1-4 dispatch units total (clusters + individual items), dispatch all in parallel. For 5+ dispatch units, batch in groups of 4.
+
+**Conflict avoidance**: No two dispatch units that touch the same file should run in parallel. Before dispatching, check for file overlaps across all dispatch units (clusters and individual items). If a cluster's file list overlaps with an individual item's file, or with another cluster's files, serialize those units -- dispatch one, wait for it to complete, then dispatch the next. Non-overlapping units can still run in parallel. Within a single dispatch unit handling multiple threads on the same file, the agent addresses them sequentially.
+
+**Sequential fallback**: Platforms that do not support parallel dispatch should run agents sequentially. Dispatch cluster units first (they are higher-leverage), then individual items.
+
+Fixes can occasionally expand beyond their referenced file (e.g., renaming a method updates callers elsewhere). This is rare but can cause parallel agents to collide. The verification step (step 8) catches this -- if re-fetching shows unresolved threads or if the commit reveals inconsistent changes, re-run the affected agents sequentially.
+
+### 6. Commit and Push
+
+After all agents complete, check whether any files were actually changed. If all verdicts are `replied`, `not-addressing`, or `needs-human` (no code changes), skip this step entirely and proceed to step 7.
+
+If there are file changes:
+
+1. Stage only files reported by sub-agents and commit with a message referencing the PR:
+
+```bash
+git add [files from agent summaries]
+git commit -m "Address PR review feedback (#PR_NUMBER)
+
+- [list changes from agent summaries]"
+```
+
+2. Push to remote:
+```bash
+git push
+```
+
+### 7. Reply and Resolve
+
+After the push succeeds, post replies and resolve where applicable. The mechanism depends on the feedback type.
+
+#### Reply format
+
+All replies should quote the relevant part of the original feedback for continuity. Quote the specific sentence or passage being addressed, not the entire comment if it's long.
+
+For fixed items:
+```markdown
+> [quoted relevant part of original feedback]
+
+Addressed: [brief description of the fix]
+```
+
+For items not addressed:
+```markdown
+> [quoted relevant part of original feedback]
+
+Not addressing: [reason with evidence, e.g., "null check already exists at line 85"]
+```
+
+For `needs-human` verdicts, post the reply but do NOT resolve the thread. Leave it open for human input.
+
+#### Review threads
+
+1. **Reply** using [scripts/reply-to-pr-thread](scripts/reply-to-pr-thread):
+```bash
+echo "REPLY_TEXT" | bash scripts/reply-to-pr-thread THREAD_ID
+```
+
+2. **Resolve** using [scripts/resolve-pr-thread](scripts/resolve-pr-thread):
+```bash
+bash scripts/resolve-pr-thread THREAD_ID
+```
+
+#### PR comments and review bodies
+
+These cannot be resolved via GitHub's API. Reply with a top-level PR comment referencing the original:
+
+```bash
+gh pr comment PR_NUMBER --body "REPLY_TEXT"
+```
+
+Include enough quoted context in the reply so the reader can follow which comment is being addressed without scrolling.
+
+### 8. Verify
+
+Re-fetch feedback to confirm resolution:
+
+```bash
+bash scripts/get-pr-comments PR_NUMBER
+```
+
+The `review_threads` array should be empty (except `needs-human` items).
+
+**If new threads remain**, check the iteration count for this run:
+
+- **First or second fix-verify cycle**: Repeat from step 2 for the remaining threads. The re-fetch in step 1 will pick up threads resolved in earlier cycles as resolved threads in `cross_invocation`, so the cross-invocation gate (step 3) will fire naturally if patterns emerge across cycles.
+
+- **After the second fix-verify cycle** (3rd pass would begin): Stop looping. Surface remaining issues to the user with context about the recurring pattern: "Multiple rounds of feedback on [area/theme] suggest a deeper issue. Here's what we've fixed so far and what keeps appearing." Use the same `needs-human` escalation pattern -- leave threads open and present the pattern for the user to decide.
+
+PR comments and review bodies have no resolve mechanism, so they will still appear in the output. Verify they were replied to by checking the PR conversation.
+
+### 9. Summary
+
+Present a concise summary of all work done. Group by verdict, one line per item describing *what was done* not just *where*. This is the primary output the user sees.
+
+Format:
+
+```
+Resolved N of M new items on PR #NUMBER:
+
+Fixed (count): [brief description of each fix]
+Fixed differently (count): [what was changed and why the approach differed]
+Replied (count): [what questions were answered]
+Not addressing (count): [what was skipped and why]
+```
+
+If any clusters were investigated, append a cluster investigation section:
+
+```
+Cluster investigations (count):
+
+1. [theme] in [area]: [cluster_assessment from the agent --
+   what was found, whether a holistic or individual approach was taken]
+```
+
+If any agent returned `needs-human`, append a decisions section. These are rare but high-signal. Each `needs-human` agent returns a `decision_context` field with a structured analysis: what the reviewer said, what the agent investigated, why it needs a decision, concrete options with tradeoffs, and the agent's lean if it has one.
+
+Present the `decision_context` directly -- it's already structured for the user to read and decide quickly:
+
+```
+Needs your input (count):
+
+1. [decision_context from the agent -- includes quoted feedback,
+   investigation findings, why it needs a decision, options with
+   tradeoffs, and the agent's recommendation if any]
+```
+
+The `needs-human` threads already have a natural-sounding acknowledgment reply posted and remain open on the PR.
+
+If there are **pending decisions from a previous run** (threads detected in step 2 as already responded to but still unresolved), surface them after the new work:
+
+```
+Still pending from a previous run (count):
+
+1. [Thread path:line] -- [brief description of what's pending]
+   Previous reply: [link to the existing reply]
+   [Re-present the decision options if the original context is available,
+   or summarize what was asked]
+```
+
+If a blocking question tool is available, use it to ask about all pending decisions (both new `needs-human` and previous-run pending) together. If there are only pending decisions and no new work was done, the summary is just the pending items.
+
+If a blocking question tool is available (`question` in OpenCode, `request_user_input` in Codex, `ask_user` in Gemini), use it to present the decisions and wait for the user's response. After they decide, process the remaining items: fix the code, compose the reply, post it, and resolve the thread.
+
+If no question tool is available, present the decisions in the summary output and wait for the user to respond in conversation. If they don't respond, the items remain open on the PR for later handling.
+
+---
+
+## Targeted Mode
+
+When a specific comment or thread URL is provided:
+
+### 1. Extract Thread Context
+
+Parse the URL to extract OWNER, REPO, PR number, and comment REST ID:
+```
+https://github.com/OWNER/REPO/pull/NUMBER#discussion_rCOMMENT_ID
+```
+
+**Step 1** -- Get comment details and GraphQL node ID via REST (cheap, single comment):
+```bash
+gh api repos/OWNER/REPO/pulls/comments/COMMENT_ID \
+  --jq '{node_id, path, line, body}'
+```
+
+**Step 2** -- Map comment to its thread ID. Use [scripts/get-thread-for-comment](scripts/get-thread-for-comment):
+```bash
+bash scripts/get-thread-for-comment PR_NUMBER COMMENT_NODE_ID [OWNER/REPO]
+```
+
+This fetches thread IDs and their first comment IDs (minimal fields, no bodies) and returns the matching thread with full comment details.
+
+### 2. Fix, Reply, Resolve
+
+Spawn a single `systematic:workflow:pr-comment-resolver` agent for the thread. Then follow the same commit -> push -> reply -> resolve flow as Full Mode steps 6-7.
+
+---
+
+## Scripts
+
+- [scripts/get-pr-comments](scripts/get-pr-comments) -- GraphQL query for unresolved review threads
+- [scripts/get-thread-for-comment](scripts/get-thread-for-comment) -- Map a comment node ID to its parent thread (for targeted mode)
+- [scripts/reply-to-pr-thread](scripts/reply-to-pr-thread) -- GraphQL mutation to reply within a review thread
+- [scripts/resolve-pr-thread](scripts/resolve-pr-thread) -- GraphQL mutation to resolve a thread by ID
+
+## Success Criteria
+
+- All unresolved review threads evaluated
+- Valid fixes committed and pushed
+- Each thread replied to with quoted context
+- Threads resolved via GraphQL (except `needs-human`)
+- Empty result from get-pr-comments on verify (minus intentionally-open threads)

package/skills/resolve-pr-feedback/scripts/get-pr-comments

@@ -0,0 +1,104 @@
+#!/usr/bin/env bash
+
+set -e
+
+if [ $# -lt 1 ]; then
+    echo "Usage: get-pr-comments PR_NUMBER [OWNER/REPO]"
+    echo "Example: get-pr-comments 123"
+    echo "Example: get-pr-comments 123 EveryInc/cora"
+    exit 1
+fi
+
+PR_NUMBER=$1
+
+if [ -n "$2" ]; then
+    OWNER=$(echo "$2" | cut -d/ -f1)
+    REPO=$(echo "$2" | cut -d/ -f2)
+else
+    OWNER=$(gh repo view --json owner -q .owner.login 2>/dev/null)
+    REPO=$(gh repo view --json name -q .name 2>/dev/null)
+fi
+
+if [ -z "$OWNER" ] || [ -z "$REPO" ]; then
+    echo "Error: Could not detect repository. Pass OWNER/REPO as second argument."
+    exit 1
+fi
+
+# Fetch review threads, regular PR comments, and review bodies in one query.
+# Output is a JSON object with four keys:
+#   review_threads   - unresolved, non-outdated inline code review threads
+#   pr_comments      - top-level PR conversation comments (excludes PR author)
+#   review_bodies    - review submissions with non-empty body text (excludes PR author)
+#   cross_invocation - cross-invocation awareness envelope:
+#     signal: true when both resolved and unresolved threads exist (multi-round review)
+#     resolved_threads: last N resolved threads by recency, for cluster analysis input
+gh api graphql -f owner="$OWNER" -f repo="$REPO" -F pr="$PR_NUMBER" -f query='
+query FetchPRFeedback($owner: String!, $repo: String!, $pr: Int!) {
+  repository(owner: $owner, name: $repo) {
+    pullRequest(number: $pr) {
+      author { login }
+      reviewThreads(first: 50) {
+        edges {
+          node {
+            id
+            isResolved
+            isOutdated
+            path
+            line
+            comments(first: 10) {
+              nodes {
+                id
+                author { login }
+                body
+                createdAt
+                url
+              }
+            }
+          }
+        }
+      }
+      comments(first: 100) {
+        nodes {
+          id
+          author { login }
+          body
+          createdAt
+          url
+        }
+      }
+      reviews(first: 50) {
+        nodes {
+          id
+          author { login }
+          body
+          state
+          createdAt
+          url
+        }
+      }
+    }
+  }
+}' | jq '.data.repository.pullRequest as $pr |
+  # Unresolved threads (existing behavior, unchanged)
+  [$pr.reviewThreads.edges[]
+    | select(.node.isResolved == false and .node.isOutdated == false)] as $unresolved |
+  # Resolved threads for cross-invocation awareness (last 10 by most recent comment)
+  [$pr.reviewThreads.edges[]
+    | select(.node.isResolved == true)
+    | { thread_id: .node.id, path: .node.path, line: .node.line,
+        first_comment_body: .node.comments.nodes[0].body,
+        last_comment_at: ([.node.comments.nodes[].createdAt] | sort | last) }]
+    | sort_by(.last_comment_at) | .[-10:] | reverse as $resolved |
+{
+  review_threads: $unresolved,
+  pr_comments: [$pr.comments.nodes[]
+    | select(.author.login != $pr.author.login)
+    | select(.body | test("^\\s*$") | not)],
+  review_bodies: [$pr.reviews.nodes[]
+    | select(.body != null and .body != "")
+    | select(.author.login != $pr.author.login)],
+  cross_invocation: {
+    signal: (($resolved | length) > 0 and ($unresolved | length) > 0),
+    resolved_threads: $resolved
+  }
+}'

package/skills/resolve-pr-feedback/scripts/get-thread-for-comment

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+
+# Maps a PR review comment node ID to its parent thread.
+# Fetches thread IDs and first comment IDs to find the match,
+# then returns the matching thread with full comment details.
+
+set -e
+
+if [ $# -lt 2 ]; then
+    echo "Usage: get-thread-for-comment PR_NUMBER COMMENT_NODE_ID [OWNER/REPO]"
+    echo "Example: get-thread-for-comment 378 PRRC_kwDOP_gZVc6ySv89"
+    exit 1
+fi
+
+PR_NUMBER=$1
+COMMENT_NODE_ID=$2
+
+if [ -n "$3" ]; then
+    OWNER=$(echo "$3" | cut -d/ -f1)
+    REPO=$(echo "$3" | cut -d/ -f2)
+else
+    OWNER=$(gh repo view --json owner -q .owner.login 2>/dev/null)
+    REPO=$(gh repo view --json name -q .name 2>/dev/null)
+fi
+
+if [ -z "$OWNER" ] || [ -z "$REPO" ]; then
+    echo "Error: Could not detect repository. Pass OWNER/REPO as third argument."
+    exit 1
+fi
+
+gh api graphql -f owner="$OWNER" -f repo="$REPO" -F pr="$PR_NUMBER" -f query='
+query($owner: String!, $repo: String!, $pr: Int!) {
+  repository(owner: $owner, name: $repo) {
+    pullRequest(number: $pr) {
+      reviewThreads(first: 100) {
+        nodes {
+          id
+          isResolved
+          path
+          line
+          comments(first: 100) {
+            nodes {
+              id
+              author { login }
+              body
+              createdAt
+              url
+            }
+          }
+        }
+      }
+    }
+  }
+}' | jq -e --arg cid "$COMMENT_NODE_ID" '
+  [.data.repository.pullRequest.reviewThreads.nodes[]
+  | select(.comments.nodes | map(.id) | index($cid))]
+  | if length == 0 then error("No thread found for comment \($cid)") else .[0] end
+'

package/skills/resolve-pr-feedback/scripts/reply-to-pr-thread

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+
+# Replies to a PR review thread. Body is read from stdin to avoid
+# shell escaping issues with markdown (quotes, newlines, etc.).
+
+set -e
+
+if [ $# -lt 1 ]; then
+    echo "Usage: echo 'reply body' | reply-to-pr-thread THREAD_ID"
+    echo "Example: echo 'Addressed: added null check' | reply-to-pr-thread PRRT_kwDOABC123"
+    exit 1
+fi
+
+THREAD_ID=$1
+BODY=$(cat)
+
+if [ -z "$BODY" ]; then
+    echo "Error: No body provided on stdin."
+    exit 1
+fi
+
+gh api graphql -f threadId="$THREAD_ID" -f body="$BODY" -f query='
+mutation ReplyToReviewThread($threadId: ID!, $body: String!) {
+  addPullRequestReviewThreadReply(input: {
+    pullRequestReviewThreadId: $threadId
+    body: $body
+  }) {
+    comment {
+      id
+      url
+    }
+  }
+}'

package/skills/todo-create/SKILL.md

@@ -0,0 +1,109 @@
+---
+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/systematic/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/systematic/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/systematic/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 todo template included below 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/systematic/todos/`
+2. Search both paths for `[0-9]*-*.md`, find the highest numeric prefix, increment, zero-pad to 3 digits.
+3. Use the todo template included below, 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 mode:autofix` -> 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 (`todowrite`/`TaskUpdate` in OpenCode, `update_plan` in Codex) instead.
+
+---
+
+## Todo Template
+
+@./assets/todo-template.md