kaitranntt Maintainer - Daily Issue Resolution Pipeline
Run the end-to-end issue triage and resolution pipeline for daily maintenance work.
Language rule: Write all conversation, reports, issues, PRs, and commits in English. Translate non-English user input before processing it. Never switch languages mid-conversation.
Arguments
| Flag | Description |
|---|---|
| (input) | User report, transcript, image, GitHub issue URL, or plain description |
--tdd |
Tests-first: write regression tests before code changes, verify after |
--parallel |
Multi-agent parallel execution (plan with file ownership, then cook with parallel agents) |
--deep |
Deep analysis: per-area scouting and thorough research before implementation |
--force-ui |
Hard-gate UI evidence: block PR until screenshots/report exist and are user-approved |
--skip-issue |
Skip GitHub issue creation because the issue already exists |
--skip-worktree |
Skip worktree creation only when already in a dedicated branch/worktree |
--pr-main |
Target the PR to main instead of dev |
--decompose |
Decompose into parallel sub-issues with separate worktrees; auto-suggest if more than three files span more than two domains |
--scan-reviews |
Standalone mode: scan open PRs for unresolved review feedback |
--from-signals |
Observe-only intake: read drift, submodule, CI, issue, and PR signals; rank them; ask the user to choose |
--max-fix-attempts N |
Set review-loop iterations (default: 5) |
--no-review-loop |
Skip the review feedback loop after PR creation |
"PR done" |
Run post-merge cleanup for worktrees and branches |
Compose --tdd, --parallel, --deep, and --force-ui as needed.
Core Invariants
- Keep
--from-signalsread-only. Never auto-pick a target or mutate state during signal intake. - Preserve issue origin: distinguish a workflow-created issue from a user-provided issue so Step 5.5 can sync correctly. A user-provided issue may be claimed or labeled in Step 3, but never comment on or close a user-opened issue without explicit user authorization; confirm before any Step 5.5 comment.
- Use worktrees for code changes. Allow
--skip-worktreeonly when already inside a dedicated worktree/branch. - Let the maintainer own commits, pushes, PR creation, and cleanup. When a plan runs, stop
/cookbefore its finalize step. - Save reports, brainstorm outputs, and plans in the target repository's
plans/directory, not its worktree. Worktrees hold code changes only. - Treat
--force-uias a blocking evidence gate. Do not create a PR until the user has reviewed the evidence.
Auto-Classification
Analyze the input and classify it as BUG or FEATURE:
| Type | Signals | Route |
|---|---|---|
| BUG | "broken", "error", "crash", "doesn't work", "regression", label bug |
Step 1a -> Step 2 -> Step 5 (/fix) |
| FEATURE | "add", "new", "would be nice", "enhance", "improve", label feat or enhancement |
Step 2.5 -> Step 3 -> Step 4 -> Step 5 (/cook) |
| Ambiguous | No decisive signal | Default to BUG: Step 1a -> Step 2 |
Flag Routing Matrix
Use this matrix in Step 5:
| Classification | No flags | --tdd |
--parallel |
--deep |
--parallel --deep |
--parallel --tdd |
|---|---|---|---|---|---|---|
| BUG | /fix --parallel |
/fix --parallel + TDD |
/ck:plan --parallel -> /cook --parallel |
/ck:plan --deep -> /cook --auto |
/ck:plan --deep -> /cook --parallel |
/ck:plan --parallel --tdd -> /cook --parallel --tdd |
| FEATURE | /cook --auto |
/cook --auto --tdd |
/ck:plan --parallel -> /cook --parallel |
/ck:plan --deep -> /cook |
/ck:plan --deep -> /cook --parallel |
/ck:plan --parallel --tdd -> /cook --parallel --tdd |
Apply these routing rules:
- Insert
/ck:planbefore implementation whenever--parallelor--deepis present, including for BUGs. - Treat
--deepas planning thoroughness and--parallelas execution strategy. They are orthogonal. - Append
--tddto the selected implementation route. - Treat
--decomposeas orthogonal. Run the selected route independently for each sub-issue. - Stop
/cookbefore its finalize step because the maintainer owns Git operations.
Workflow
Input
|
+-- --from-signals -> [0/0a] read signals -> USER chooses target
|
v
[1] classify BUG or FEATURE
|
+-- BUG -> [1a] /brainstorm -> [2] /debug
+-- FEATURE ------------------------------+
|
v
[2.5] complexity check
|
+----------------+----------------+
| |
simple --decompose
| |
v v
[3] create/claim issue [3/3.5] parent + sub-issues
| |
v v
[4] /worktree worktree per sub-issue
| |
+----------------+----------------+
|
v
[4.5] optional /ck:plan
|
v
[5] flag-routed implementation
|
v
[5.5] progress comment
|
v
[6] /preview --explain
|
v
[7] optional parallel code review
|
v
[7.5] conditional UI evidence
|
v
[8] PR + Closes #N
|
v
[8.5] review/fix loop
|
v
[9] "PR done" cleanup
Reference Loading Rules
Read only the reference files required for the active mode or current step. Every reference is one level below this file.
| Mode or Step | Required Action | Direct Reference |
|---|---|---|
--from-signals (0, 0a) |
Read before running the suggester, presenting candidates, or accepting a target. | references/signal-intake.md |
| Triage/classification (1, 1a, 2, 2.5) | Read before classifying, brainstorming/debugging a BUG, or deciding decomposition. FEATURE skips Step 2 but keeps Step 2.5. | references/triage-and-classify.md |
| GitHub issue/decomposition (3, 3.5) | Read before claiming/creating an issue or using --decompose. Skip issue operations with --skip-issue. |
references/github-and-decompose.md |
| Worktree through PR (4, 4.5, 5, 5.5, 6, 7, 8) | Read before creating a worktree, planning, implementing, reporting progress, previewing, reviewing, or opening the PR. | references/implement-and-pr.md |
| Normal UI evidence (7.5) | Read both references when UI files changed and --force-ui is absent. Skip only for non-UI changes. |
references/ui-diff-evidence.md and references/force-ui-evidence.md |
Forced evidence (7.5 with --force-ui) |
Read whenever --force-ui is present, including backend-only changes. This is a hard gate. |
references/force-ui-evidence.md |
| Review loop (8.5) | Read after PR creation unless --no-review-loop; also read when scan mode finds actionable feedback. |
references/review-feedback-loop.md |
| Cleanup (9) | Read only after the user says "PR done"; verify merge before cleanup. |
references/cleanup-and-rules.md |
--scan-reviews standalone mode |
Read first and run this mode instead of the issue-to-PR pipeline. | references/scan-reviews.md |
For UI work with --force-ui, read both references/ui-diff-evidence.md for capture rules and references/force-ui-evidence.md for gate, mode, report, and PR-body requirements.
Completion
Do not stop at code edits. Complete the selected route through focused validation, reviewable explanation, PR handling, feedback resolution, and task-scoped cleanup when authorized.