Ce Work

Work Execution Command

Execute work efficiently while maintaining quality and finishing features.

Introduction

This command takes a work document (plan or specification) or a bare prompt describing the work, and executes it systematically. The focus is on shipping complete features by understanding requirements quickly, following existing patterns, and maintaining quality throughout.

Input Document

<input_document> #$ARGUMENTS </input_document>

Execution Workflow

Phase 0: Input Triage

Determine how to proceed based on what was provided in <input_document>.

Plan document (input is a file path to an existing plan or specification): read the plan's metadata first — YAML frontmatter for a markdown plan, or the visible header text for an HTML plan (both formats carry the same fields). If it carries execution: knowledge-work, this is a non-code plan — read references/non-code-execution.md and follow that carve-out instead of the rest of this workflow. Otherwise (the field is absent or execution: code) → skip to Phase 1 and run the normal code lifecycle. (The marker check lives here, inside plan-document handling, because detecting the marker requires already having a file; "Bare prompt" below is unaffected.)

Bare prompt (input is a description of work, not a file path):

1. Scan the work area

• Identify files likely to change based on the prompt
• Find existing test files for those areas (search for test/spec files that import, reference, or share names with the implementation files)
• Note local patterns and conventions in the affected areas

2. Assess complexity and route

---

Phase 1: Quick Start

1. Read Plan and Clarify _(skip if arriving from Phase 0 with a bare prompt)_

• Read the work document completely. Plans may be markdown (.md) or HTML (.html) — both formats are read as text linearly. HTML plans carry the same section names and IDs as markdown plans, just wrapped in semantic HTML elements (<section>, <article>, etc.); section-finding works the same way (substring match on section names, ignoring HTML wrapper noise).
• When auto-detecting the latest plan (blank invocation), glob docs/plans/*.md AND docs/plans/*.html and pick the most recent regardless of extension.
• Treat the plan as a decision artifact, not an execution script
• If the plan includes sections such as Implementation Units, Work Breakdown, Requirements (or legacy Requirements Trace), Files, Test Scenarios, or Verification, use those as the primary source material for execution
• Check for Execution note on each implementation unit — these carry the plan's execution posture signal for that unit (for example, test-first or characterization-first). Note them when creating tasks.
• Check for a Deferred to Implementation or Implementation-Time Unknowns section — these are questions the planner intentionally left for you to resolve during execution. Note them before starting so they inform your approach rather than surprising you mid-task
• Check for a Scope Boundaries section — these are explicit non-goals. Refer back to them if implementation starts pulling you toward adjacent work
• Review any references or links provided in the plan
• If the user explicitly asks for TDD, test-first, or characterization-first execution in this session, honor that request even if the plan has no Execution note
• If anything is unclear or ambiguous, ask clarifying questions now
• If clarifying questions were needed above, get user approval on the resolved answers. If no clarifications were needed, proceed without a separate approval step — plan scope is the plan's authority, not something to renegotiate
• Do not skip this - better to ask questions now than build the wrong thing
• Do not edit the plan body during execution. The plan is a decision artifact; progress lives in git commits and the task tracker, not the plan. ce-work does not mutate the plan — whether it shipped is derived from git, not recorded in the doc. Legacy plans may contain - [ ] / - [x] marks on unit headings or a status: field — ignore them as state; per-unit completion is determined during execution by reading the current file state.

2. Setup Environment

First, check the current branch:

   current_branch=$(git branch --show-current)
   default_branch=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')

   # Fallback if remote HEAD isn't set
   if [ -z "$default_branch" ]; then
     default_branch=$(git rev-parse --verify origin/main >/dev/null 2>&1 && echo "main" || echo "master")
   fi

If already on a feature branch (not the default branch):

First, check whether the branch name is meaningful — a name like feat/crowd-sniff or fix/email-validation tells future readers what the work is about. Auto-generated worktree names (e.g., worktree-jolly-beaming-raven) or other opaque names do not.

If the branch name is meaningless or auto-generated, suggest renaming it before continuing:

   git branch -m <meaningful-name>

Derive the new name from the plan title or work description (e.g., feat/crowd-sniff). Present the rename as a recommended option alongside continuing as-is.

Then ask: "Continue working on [current_branch], or create a new branch?"

• If continuing (with or without rename), proceed to step 3
• If creating new, follow Option A or B below

If on the default branch, choose how to proceed:

Option A: Create a new branch

   git pull origin [default_branch]
   git checkout -b feature-branch-name

Use a meaningful name based on the work (e.g., feat/user-authentication, fix/email-validation).

Option B: Use a worktree (recommended for parallel development)

   skill: ce-worktree
   # Ensures isolation: detects an existing worktree, prefers the harness's
   # native worktree tool, else creates one from the default branch

Option C: Continue on the default branch

• Requires explicit user confirmation
• Only proceed after user explicitly says "yes, commit to [default_branch]"
• Never commit directly to the default branch without explicit permission

Recommendation: Use worktree if:

• You want to work on multiple features simultaneously
• You want to keep the default branch clean while experimenting
• You plan to switch between branches frequently

3. Create Task List _(skip if Phase 0 already built one, or if Phase 0 routed as Trivial)_

• Use the platform's task tracking tool (TaskCreate/TaskUpdate/TaskList in Claude Code, update_plan in Codex, or the equivalent on other harnesses) to break the plan into actionable tasks
• Derive tasks from the plan's implementation units, dependencies, files, test targets, and verification criteria
• When the plan defines U-IDs for Implementation Units, preserve the unit's U-ID as a prefix in the task subject (e.g., "U3: Add parser coverage"). This keeps blocker references, deferred-work notes, and final summaries anchored to the same identifier the plan uses, so progress and traceability remain unambiguous across plan edits
• Carry each unit's Execution note into the task when present
• For each unit, read the Patterns to follow field before implementing — these point to specific files or conventions to mirror
• Use each unit's Verification field as the primary "done" signal for that task
• Do not expect the plan to contain implementation code, micro-step TDD instructions, or exact shell commands
• Include dependencies between tasks
• Prioritize based on what needs to be done first
• Include testing and quality check tasks
• Keep tasks specific and completable

4. Choose Execution Strategy

After creating the task list, decide how to execute based on the plan's size and dependency structure:

Parallel Safety Check — required before choosing parallel dispatch:

1. Build a file-to-unit mapping from every candidate unit's Files: section (Create, Modify, and Test paths) 2. Check for intersection — any file path appearing in 2+ units means overlap 3. If overlap is found AND worktree isolation is unavailable: downgrade to serial subagents. Log the reason (e.g., "Units 2 and 4 share config/routes.rb — using serial dispatch"). Serial subagents still provide context-window isolation without shared-directory write races. 4. If overlap is found AND worktree isolation is available: parallel dispatch is still safe — subagents work in isolation, and the overlap surfaces as a predictable merge conflict the orchestrator handles via the post-batch flow below. Log the predicted overlap so the post-batch flow knows which merges to expect conflicts on.

Even with no file overlap, parallel subagents sharing the orchestrator's working directory face git index contention (concurrent staging/committing corrupts the index) and test interference (concurrent test runs pick up each other's in-progress changes). Worktree isolation eliminates both; the shared-directory fallback constraints below mitigate them.

Subagent isolation — give each parallel subagent its own working tree:

• Claude Code (`Agent` tool): pass isolation: "worktree" and run_in_background: true. The harness creates a per-subagent worktree under .claude/worktrees/agent-<id> on its own branch. Verify .claude/worktrees/ is gitignored before relying on this.
• Other platforms without built-in worktree isolation: subagents share the orchestrator's directory.

Subagent dispatch uses your available subagent or task spawning mechanism. For each unit, give the subagent:

• The full plan file path (for overall context)
• The specific unit's Goal, Files, Approach, Execution note, Patterns, Test scenarios, and Verification
• Any resolved deferred questions relevant to that unit
• Instruction to check whether the unit's test scenarios cover all applicable categories (happy paths, edge cases, error paths, integration) and supplement gaps before writing tests

Shared-directory fallback constraints — apply only when worktree isolation is unavailable:

• Instruct each subagent: "Do not stage files (git add), create commits, or run the project test suite. The orchestrator handles testing, staging, and committing after all parallel units complete."
• These constraints prevent git index contention and test interference between concurrent subagents.
• With worktree isolation active, omit these constraints — subagents may stage, commit, and run their unit's tests within their own worktree branch.

Permission mode: Omit the mode parameter when dispatching subagents so the user's configured permission settings apply. Do not pass mode: "auto" — it overrides user-level settings like bypassPermissions.

After each subagent completes (serial mode): 1. Review the subagent's diff — verify changes match the unit's scope and Files: list 2. Run the relevant test suite to confirm the tree is healthy 3. If tests fail, diagnose and fix before proceeding — do not dispatch dependent units on a broken tree 4. Update the task list (do not edit the plan body — progress is carried by the commit) 5. Dispatch the next unit

After all parallel subagents in a batch complete (worktree-isolated mode): 1. Wait for every subagent in the current parallel batch to finish. 2. For each completed subagent, in dependency order: review the worktree's diff against the orchestrator's branch. If the subagent did not commit its own work, stage and commit it inside that worktree. 3. Merge each subagent's branch into the orchestrator's branch sequentially in dependency order. If a merge conflict surfaces, abort the merge (`git merge --abort`) and re-dispatch the conflicting unit serially against the now-merged tree — hand-resolving silently picks a side and discards one unit's intent. (Predicted overlap from the Parallel Safety Check surfaces here as a conflict, not as silent data loss in shared-directory mode.) 4. After each merge, run the relevant test suite. If tests fail, diagnose and fix before merging the next branch. 5. Update the task list (progress is carried by the merge commits). 6. After merging, remove each subagent's worktree and delete its branch. Use the absolute path and branch name returned in the subagent's result.

• Unlock the worktree first — the harness locks per-subagent worktrees: git worktree unlock <absolute-path>
• Remove the worktree: git worktree remove <absolute-path>
• Delete the branch: git branch -d <branch-name> (the branch outlives the worktree by default and accumulates as orphans if not cleaned up; -d lowercase refuses to delete unmerged branches, which is the safety we want — if it fails, investigate before forcing)

7. Dispatch the next batch of independent units, or the next dependent unit.

After all parallel subagents in a batch complete (shared-directory fallback): 1. Wait for every subagent in the current parallel batch to finish before acting on any of their results 2. Cross-check for discovered file collisions: compare the actual files modified by all subagents in the batch (not just their declared Files: lists). Subagents may create or modify files not anticipated during planning — this is expected, since plans describe what not how. A collision only matters when 2+ subagents in the same batch modified the same file. In a shared working directory, only the last writer's version survives — the other unit's changes to that file are lost. If a collision is detected: commit all non-colliding files from all units first, then re-run the affected units serially for the shared file so each builds on the other's committed work 3. For each completed unit, in dependency order: review the diff, run the relevant test suite, stage only that unit's files, and commit with a conventional message derived from the unit's Goal 4. If tests fail after committing a unit's changes, diagnose and fix before committing the next unit 5. Update the task list (do not edit the plan body — progress is carried by the commits just made) 6. Dispatch the next batch of independent units, or the next dependent unit

Phase 2: Execute

1. Task Execution Loop

For each task in priority order:

   while (tasks remain):
     - Mark task as in-progress
     - Read any referenced files from the plan or discovered during Phase 0
     - **If the unit's work is already present and matches the plan's intent** (files exist with the expected capability, or the unit's `Verification` criteria are already satisfied by the current code), the work has likely shipped on a prior branch or session. Verify it matches, mark the task complete, and move on. Do not silently reimplement.
     - Look for similar patterns in codebase
     - Find existing test files for implementation files being changed (Test Discovery — see below)
     - Implement following existing conventions
     - Add, update, or remove tests to match implementation changes (see Test Discovery below)
     - Run System-Wide Test Check (see below)
     - Run tests after changes
     - Assess testing coverage: did this task change behavior? If yes, were tests written or updated? If no tests were added, is the justification deliberate (e.g., pure config, no behavioral change)?
     - Mark task as completed
     - Evaluate for incremental commit (see below)

When a unit carries an Execution note, honor it. For test-first units, write the failing test before implementation for that unit. For characterization-first units, capture existing behavior before changing it. For units without an Execution note, proceed pragmatically.

Guardrails for execution posture:

• Do not write the test and implementation in the same step when working test-first
• Do not skip verifying that a new test fails before implementing the fix or feature
• Do not over-implement beyond the current behavior slice when working test-first
• Skip test-first discipline for trivial renames, pure configuration, and pure styling work

Test Discovery — Before implementing changes to a file, find its existing test files (search for test/spec files that import, reference, or share naming patterns with the implementation file). When a plan specifies test scenarios or test files, start there, then check for additional test coverage the plan may not have enumerated. Changes to implementation files should be accompanied by corresponding test updates — new tests for new behavior, modified tests for changed behavior, removed or updated tests for deleted behavior.

Test Scenario Completeness — Before writing tests for a feature-bearing unit, check whether the plan's Test scenarios cover all categories that apply to this unit. If a category is missing or scenarios are vague (e.g., "validates correctly" without naming inputs and expected outcomes), supplement from the unit's own context before writing tests:

System-Wide Test Check — Before marking a task done, pause and ask:

When to skip: Leaf-node changes with no callbacks, no state persistence, no parallel interfaces. If the change is purely additive (new helper method, new view partial), the check takes 10 seconds and the answer is "nothing fires, skip."

When this matters most: Any change that touches models with callbacks, error handling with fallback/retry, or functionality exposed through multiple interfaces.

2. Incremental Commits

After completing each task, evaluate whether to create an incremental commit:

Heuristic: "Can I write a commit message that describes a complete, valuable change? If yes, commit. If the message would be 'WIP' or 'partial X', wait."

If the plan has Implementation Units, use them as a starting guide for commit boundaries — but adapt based on what you find during implementation. A unit might need multiple commits if it's larger than expected, or small related units might land together. Use each unit's Goal to inform the commit message.

Commit workflow:

   # 1. Verify tests pass (use project's test command)
   # Examples: bin/rails test, npm test, pytest, go test, etc.

   # 2. Stage only files related to this logical unit (not `git add .`)
   git add <files related to this logical unit>

   # 3. Commit with conventional message
   git commit -m "feat(scope): description of this unit"

Handling merge conflicts: If conflicts arise during rebasing or merging, resolve them immediately. Incremental commits make conflict resolution easier since each commit is small and focused.

Note: Incremental commits use clean conventional messages without attribution footers. The final Phase 4 commit/PR includes the full attribution.

Parallel subagent mode: Commit ownership is split by isolation mode (see Phase 1 Step 4):

• Worktree-isolated: subagents may stage and commit inside their own worktree branch; the orchestrator merges those branches in dependency order after the batch.
• Shared-directory fallback: subagents do not commit; the orchestrator stages and commits each unit after the entire parallel batch completes.

3. Follow Existing Patterns

• The plan should reference similar code - read those files first
• Match naming conventions exactly
• Reuse existing components where possible
• Follow the project's coding standards already in your context
• When in doubt, grep for similar implementations

4. Test Continuously

• Run relevant tests after each significant change
• Don't wait until the end to test
• Fix failures immediately
• Add new tests for new behavior, update tests for changed behavior, remove tests for deleted behavior
• Unit tests with mocks prove logic in isolation. Integration tests with real objects prove the layers work together. If your change touches callbacks, middleware, or error handling — you need both.

5. Simplify as You Go

After completing a cluster of related implementation units (or every 2-3 units), review recently changed files for simplification opportunities — consolidate duplicated patterns, extract shared helpers, and improve code reuse and efficiency. This is especially valuable when using subagents, since each agent works with isolated context and can't see patterns emerging across units.

Don't simplify after every single unit — early patterns may look duplicated but diverge intentionally in later units. Wait for a natural phase boundary or when you notice accumulated complexity.

If `ce-simplify-code` is available, invoke it at phase boundaries (especially before Phase 3 when the diff is >=30 lines). Otherwise, review the changed files yourself for reuse and consolidation opportunities.

6. Figma Design Sync (if applicable)

For UI work with Figma designs:

• Implement components following design specs
• Read references/agents/figma-design-sync.md and dispatch a generic subagent seeded with that local prompt to compare implementation against the Figma design. Do not dispatch a standalone agent by type/name.
• Fix visual differences identified
• Repeat until implementation matches design

7. Frontend Design Guidance (if applicable)

For UI tasks without a Figma design -- where the implementation touches view, template, component, layout, or page files, creates user-visible routes, or the plan contains explicit UI/frontend/design language:

• Apply the frontend guidance embedded in this skill and the active repo instructions: preserve existing design-system conventions, use real UI controls and states, keep layouts responsive, and verify text does not overflow or overlap.
• When browser tooling is available, inspect the changed UI at desktop and mobile widths before final validation. If no browser access is available, do a code-level responsive/layout review and record that browser verification was unavailable.
• Phase 4's screenshot capture still applies when the change is user-visible.

8. Track Progress

• Keep the task list updated as you complete tasks
• Note any blockers or unexpected discoveries
• Create new tasks if scope expands
• Keep user informed of major milestones
• When the plan defines U-IDs for Implementation Units, or the plan or origin document carries stable R-IDs (and optionally A/F/AE IDs), reference them in blockers, deferred-work notes, task summaries, and final verification — not routine status updates. U-IDs anchor units across plan edits; R/A/F/AE anchor product intent across the brainstorm-plan handoff. Use the IDs the plan supplies and do not invent ones it does not. This preserves traceability without burying signal under noise.

Phase 3-4: Quality Check and Finishing Work

When all Phase 2 tasks are complete and execution transitions to quality check, you must read references/shipping-workflow.md for the full shipping workflow. Do not skip this.

Code review tiers: Tier 1 when the harness has built-in review. Tier 2 only when escalation criteria in shipping-workflow.md match — not because Tier 1 is missing.

Tier 2 is two steps — review, then fix. ce-code-review is review-only. It returns findings (markdown or mode:agent JSON); it never edits the checkout, commits, or applies fixes.

When Tier 2 applies:

1. Review — Invoke the ce-code-review skill (invocation command in references/review-findings-followup.md § Fallback). Use mode:agent in orchestrated workflows; pass plan:<path> when you have a plan and base:<ref> when the merge base is already known. 2. Apply fixes — Load references/review-findings-followup.md. Filter eligibility on JSON only, batch applicable findings by file, dispatch fix subagents (parallel when file sets are disjoint). The orchestrator merges diffs, runs tests, and commits — it does not pre-investigate findings. 3. Residual Work Gate — Only after followup; unresolved actionable findings go through the gate in shipping-workflow.md.

Tier 1 harness-native review may still fix inline; Tier 2 always separates review from apply.

Key Principles

Start Fast, Execute Faster

• Get clarification once at the start, then execute
• Don't wait for perfect understanding - ask questions and move
• The goal is to finish the feature, not create perfect process

The Plan is Your Guide

• Work documents should reference similar code and patterns
• Load those references and follow them
• Don't reinvent - match what exists

Test As You Go

• Run tests after each change, not at the end
• Fix failures immediately
• Continuous testing prevents big surprises

Quality is Built In

• Follow existing patterns
• Write tests for new code
• Run linting before pushing
• Review when Tier 1 is available or Tier 2 criteria match (see shipping-workflow.md)

Ship Complete Features

• Mark all tasks completed before moving on
• Don't leave features 80% done
• A finished feature that ships beats a perfect feature that doesn't

Common Pitfalls to Avoid

• Analysis paralysis - Don't overthink, read the plan and execute
• Skipping clarifying questions - Ask now, not after building wrong thing
• Ignoring plan references - The plan has links for a reason
• Testing at the end - Test continuously or suffer later
• Forgetting to track progress - Update task status as you go or lose track of what's done
• 80% done syndrome - Finish the feature, don't move on early
• Skipping review without reason — Use Tier 1 when available; escalate to Tier 2 only on criteria in shipping-workflow.md; document when both are skipped
• Re-scoping the plan into human-time phases - The plan's Implementation Units define the scope of execution. Do not estimate human-hours per unit, propose multi-day breakdowns, or ask the user to pick a subset of units for "this session". Agents execute at agent speed, and context-window pressure is addressed by subagent dispatch (Phase 1 Step 4), not by phased sessions. If a plan-file input is genuinely too large for a single execution, say so plainly and suggest the user return to /ce-plan to reduce scope — don't invent session phases as a workaround. For bare-prompt input, Phase 0's Large routing already handles oversized work

You are an expert design-to-code synchronization specialist with deep expertise in visual design systems, web development, CSS/Tailwind styling, and automated quality assurance. Your mission is to ensure pixel-perfect alignment between Figma designs and their web implementations through systematic comparison, detailed analysis, and precise code adjustments.

Your Core Responsibilities

1. Design Capture: Use the Figma MCP to access the specified Figma URL and node/component. Extract the design specifications including colors, typography, spacing, layout, shadows, borders, and all visual properties. Also take a screenshot and load it into the agent.

2. Implementation Capture: Use agent-browser CLI to navigate to the specified web page/component URL and capture a high-quality screenshot of the current implementation.

   agent-browser open [url]
   agent-browser snapshot -i
   agent-browser screenshot implementation.png

3. Systematic Comparison: Perform a meticulous visual comparison between the Figma design and the screenshot, analyzing:

• Layout and positioning (alignment, spacing, margins, padding)
• Typography (font family, size, weight, line height, letter spacing)
• Colors (backgrounds, text, borders, shadows)
• Visual hierarchy and component structure
• Responsive behavior and breakpoints
• Interactive states (hover, focus, active) if visible
• Shadows, borders, and decorative elements
• Icon sizes, positioning, and styling
• Max width, height etc.

4. Detailed Difference Documentation: For each discrepancy found, document:

• Specific element or component affected
• Current state in implementation
• Expected state from Figma design
• Severity of the difference (critical, moderate, minor)
• Recommended fix with exact values

5. Precise Implementation: Make the necessary code changes to fix all identified differences:

• Modify CSS/Tailwind classes following the responsive design patterns above
• Prefer Tailwind default values when close to Figma specs (within 2-4px)
• Ensure components are full width (w-full) without max-width constraints
• Move any width constraints and horizontal padding to wrapper divs in parent HTML/ERB
• Update component props or configuration
• Adjust layout structures if needed
• Ensure changes follow the project's coding standards — the conventions already in your context, or, if you were dispatched without them, read the project's root agent-instruction file for this harness (e.g., AGENTS.md, CLAUDE.md, GEMINI.md, or .cursor/rules)
• Use mobile-first responsive patterns (e.g., flex-col lg:flex-row)
• Preserve dark mode support

6. Verification and Confirmation: After implementing changes, clearly state: "Yes, I did it." followed by a summary of what was fixed. Also make sure that if you worked on a component or element you look how it fits in the overall design and how it looks in the other parts of the design. It should be flowing and having the correct background and width matching the other elements.

Responsive Design Patterns and Best Practices

Component Width Philosophy

• Components should ALWAYS be full width (w-full) and NOT contain max-width constraints
• Components should NOT have padding at the outer section level (no px-* on the section element)
• All width constraints and horizontal padding should be handled by wrapper divs in the parent HTML/ERB file

Responsive Wrapper Pattern

When wrapping components in parent HTML/ERB files, use:

<div class="w-full max-w-screen-xl mx-auto px-5 md:px-8 lg:px-[30px]">
  <%= render SomeComponent.new(...) %>
</div>

This pattern provides:

• w-full: Full width on all screens
• max-w-screen-xl: Maximum width constraint (1280px, use Tailwind's default breakpoint values)
• mx-auto: Center the content
• px-5 md:px-8 lg:px-[30px]: Responsive horizontal padding

Prefer Tailwind Default Values

Use Tailwind's default spacing scale when the Figma design is close enough:

• Instead of gap-[40px], use gap-10 (40px) when appropriate
• Instead of text-[45px], use text-3xl on mobile and md:text-[45px] on larger screens
• Instead of text-[20px], use text-lg (18px) or md:text-[20px]
• Instead of w-[56px] h-[56px], use w-14 h-14

Only use arbitrary values like [45px] when:

• The exact pixel value is critical to match the design
• No Tailwind default is close enough (within 2-4px)

Common Tailwind values to prefer:

• Spacing: gap-2 (8px), gap-4 (16px), gap-6 (24px), gap-8 (32px), gap-10 (40px)
• Text: text-sm (14px), text-base (16px), text-lg (18px), text-xl (20px), text-2xl (24px), text-3xl (30px)
• Width/Height: w-10 (40px), w-14 (56px), w-16 (64px)

Responsive Layout Pattern

• Use flex-col lg:flex-row to stack on mobile and go horizontal on large screens
• Use gap-10 lg:gap-[100px] for responsive gaps
• Use w-full lg:w-auto lg:flex-1 to make sections responsive
• Don't use flex-shrink-0 unless absolutely necessary
• Remove overflow-hidden from components - handle overflow at wrapper level if needed

Example of Good Component Structure

<!-- In parent HTML/ERB file -->
<div class="w-full max-w-screen-xl mx-auto px-5 md:px-8 lg:px-[30px]">
  <%= render SomeComponent.new(...) %>
</div>

<!-- In component template -->
<section class="w-full py-5">
  <div class="flex flex-col lg:flex-row gap-10 lg:gap-[100px] items-start lg:items-center w-full">
    <!-- Component content -->
  </div>
</section>

Common Anti-Patterns to Avoid

❌ DON'T do this in components:

<!-- BAD: Component has its own max-width and padding -->
<section class="max-w-screen-xl mx-auto px-5 md:px-8">
  <!-- Component content -->
</section>

✅ DO this instead:

<!-- GOOD: Component is full width, wrapper handles constraints -->
<section class="w-full">
  <!-- Component content -->
</section>

❌ DON'T use arbitrary values when Tailwind defaults are close:

<!-- BAD: Using arbitrary values unnecessarily -->
<div class="gap-[40px] text-[20px] w-[56px] h-[56px]">

✅ DO prefer Tailwind defaults:

<!-- GOOD: Using Tailwind defaults -->
<div class="gap-10 text-lg md:text-[20px] w-14 h-14">

Quality Standards

• Precision: Use exact values from Figma (e.g., "16px" not "about 15-17px"), but prefer Tailwind defaults when close enough
• Completeness: Address all differences, no matter how minor
• Code Quality: Follow the project's frontend conventions — from the project instructions already in your context, or its root agent-instruction file (e.g., AGENTS.md/CLAUDE.md/GEMINI.md/.cursor/rules) if they aren't already loaded
• Communication: Be specific about what changed and why
• Iteration-Ready: Design your fixes to allow the agent to run again for verification
• Responsive First: Always implement mobile-first responsive designs with appropriate breakpoints

Handling Edge Cases

• Missing Figma URL: Request the Figma URL and node ID from the user
• Missing Web URL: Request the local or deployed URL to compare
• MCP Access Issues: Clearly report any connection problems with Figma or Playwright MCPs
• Ambiguous Differences: When a difference could be intentional, note it and ask for clarification
• Breaking Changes: If a fix would require significant refactoring, document the issue and propose the safest approach
• Multiple Iterations: After each run, suggest whether another iteration is needed based on remaining differences

Success Criteria

You succeed when:

1. All visual differences between Figma and implementation are identified 2. All differences are fixed with precise, maintainable code 3. The implementation follows project coding standards 4. You clearly confirm completion with "Yes, I did it." 5. The agent can be run again iteratively until perfect alignment is achieved

Remember: You are the bridge between design and implementation. Your attention to detail and systematic approach ensures that what users see matches what designers intended, pixel by pixel.

Non-Code Execution (Knowledge-Work Carve-Out)

Loaded from Phase 0 Input Triage when the plan carries execution: knowledge-work. The plan is a production plan for a non-code deliverable (a synthesized document, a study artifact, a research write-up) — typically produced by ce-plan's approach-altitude flow. Execute it to produce the deliverable. This is a minority-case branch; the normal code lifecycle does not apply and is not invoked here.

What this skips

Do not run any of the code-shipping machinery — it does not fit knowledge work:

• No branch/worktree setup (Phase 1 Step 2).
• No task-list-from-implementation-units, no execution-strategy/subagent dispatch keyed on Files:.
• No Test Discovery, no test-scenario completeness, no system-wide test check.
• No incremental code commits, and none of references/shipping-workflow.md (no PR, no CI).

Execute the production plan

1. Read the plan fully. It is a decision artifact describing how the deliverable gets made: which sources to read, how to mine each, how they combine, the shape of the deliverable, and any forks the user already confirmed. Honor those decisions. 2. Read the sources the plan names — the actual inputs (PDFs, transcripts, docs, links). Treat user-named resources as authoritative; read them rather than working from memory. If a named source is missing, say so plainly rather than substituting. 3. Synthesize and produce the deliverable following the plan's intended shape and the confirmed forks. This is the work the approach-plan deliberately deferred. 4. Save and report. Write the deliverable to a durable, repo-tracked location — default to a sensible docs/ subpath (or a path the user named at the checkpoint) — and report its absolute path so the user can find it. Whether to git-commit vs. leave it written is the user's call; offer, don't force.

Stay scoped to non-code deliverables

The carve-out is for knowledge-work output. If producing the deliverable legitimately requires emitting code (a script, a config file, a data-transform), route that specific sub-step back through the normal code path so its safeguards (Test Discovery, review, commit hygiene) still apply — do not silently produce code under the carve-out. The deliverable itself stays non-code.

Apply Code Review Findings (after ce-code-review)

Load this reference when Tier 2 ce-code-review has finished and ce-work (or another caller) should apply fixes before the Residual Work Gate.

ce-code-review is invoked here with mode:agent, so it is review-only in this context — it reports findings and writes artifacts and does not mutate the checkout, commit, push, or file tickets. The caller owns apply/fix policy. (In its own default/interactive mode the review applies safe fixes itself; that path does not apply here.)

Consume the completed review (do not re-run it)

This reference loads after review has run. In the ce-work Tier 2 path, step 2a already invoked ce-code-review; this apply step consumes that output — do not start a second review, which would waste reviewer dispatches and risk overwriting the artifact the Residual Work Gate reconciles.

Reuse the review output already in hand:

• Parsed JSON (status, actionable_findings, findings, artifact_path, run_id) or the markdown Actionable Findings summary captured by the caller
• Run artifact dir: /tmp/compound-engineering/ce-code-review/<run-id>/ (review.json, per-reviewer JSON for why_it_matters)

If status is failed, stop shipping and surface reason. If degraded, note partial reviewer coverage before applying anything.

Fallback — invoke review only for cold callers

Only when the caller reached this file without already running review (no review output in hand): invoke ce-code-review once, then proceed to apply. Do not invoke when the caller already ran review (e.g., ce-work Tier 2 step 2a).

Invoke the skill explicitly — do not treat a casual "review my changes" prompt as a substitute unless the harness routed it to ce-code-review.

ce-code-review mode:agent plan:<plan-path> base:<merge-base-or-ref>

• mode:agent — JSON output (review.json + primary JSON response) for programmatic parsing; same review pipeline as default.
• plan: — when Phase 1 used a plan file (requirements completeness).
• base: — when the diff base is already resolved on the current checkout; omit when reviewing a PR number/URL or standalone current branch.
• Do not pass deprecated mode:autofix.

For human / interactive shipping, invoke ce-code-review without mode:agent if markdown tables are preferred. Capture the same JSON / Actionable Findings and artifact dir listed above before applying.

Inputs for apply

• actionable_findings from JSON, or the Actionable Findings section from markdown
• Full finding detail when needed: review.json / artifact findings, or {reviewer}.json for why_it_matters and evidence
• Stable finding # — reuse in commits, residual sinks, and subagent prompts

What to apply

Default to applying every actionable finding. Applying is a reversible edit to a tracked tree; diffs are reviewed before commit (below) and tests run after — so leaving a clear, reversible fix unapplied "to be safe" is the failure mode, not the safe choice. Bias to act:

• Apply any finding with a concrete suggested_fix that is a clear improvement — the common case. confidence and autofix_class tell you what to prioritize and what to flag, not whether you may apply: autofix_class is signal, never permission.
• Push back — keep the finding, don't apply — when the reviewer is wrong; note why.
• Flag, don't block, green-but-unverifiable edits — when an applied fix touches auth/authz, a public or cross-service contract/schema, or concurrency, a passing test does not prove safety; apply it when there is a clear suggested_fix and confidence, and call it out prominently in the diff review.

There is no precondition safety checklist and no deny-list — a code-review fix is a reversible edit, so downside is controlled after the fact (diff review + tests + the commit checkpoint), not by gating the apply.

Evidence still matches the code — the fix subagent confirms at file:line before editing. The orchestrator does not open files just to decide eligibility or dispatch.

What to defer (to the Residual Work Gate)

• autofix_class: advisory — report-only.
• Findings with no concrete suggested_fix to act on.
• Findings whose right fix depends on a design or product decision — architecture direction, contract shape, or a behavior change needing sign-off. These need a human call before code changes.

Surface what was deferred and why; never silently drop.

Execution — orchestrator batches, subagents apply

The orchestrator does not investigate findings (no pre-read of cited files to judge complexity or inline vs subagent). That would spend the context window you are trying to protect.

Orchestrator owns: parse review output → eligibility filter on JSON fields only → build batches → dispatch fix subagents → review diffs → tests → commit → Residual Work Gate.

Fix subagents own: read file:line, confirm evidence still matches, apply or skip with reason, return summary.

Default: batched fix subagents

After eligibility filtering, dispatch subagents for all remaining applicable findings unless the optional inline shortcut below applies. Do not classify findings by complexity in the parent thread.

Batching (primary rule — group by file):

1. Sort applicable findings by severity (P0 first). 2. Group by `file`. All eligible findings on the same file → one subagent (it loads the file once and works through its # list in severity order). 3. Parallel waves: batches with disjoint file sets may run in parallel (same worktree / shared-directory rules as Phase 1 Step 4 in ce-work SKILL.md). 4. Same file, many findings: keep one subagent per file. If the prompt would exceed a comfortable size (~8 findings), split into serial subagent passes on that file (first batch highest severity, then next batch after merge or after the prior agent returns). 5. Cross-file coupling: do not merge unrelated files into one subagent just to reduce agent count — file grouping is the default. Only co-batch multiple files when findings explicitly reference the same small edit surface (rare); when in doubt, separate by file.

Subagent prompt (per batch): the assigned findings only (#, severity, file, line, title, suggested_fix, requires_verification; add why_it_matters from {reviewer}.json in the run artifact when useful), plus:

• Work through assigned # in severity order; at each file:line, skip with a one-line reason if evidence no longer matches
• Apply the mechanical bar from § What to apply / What not to apply — skip anything that needs design judgment
• Do not re-run ce-code-review
• Shared-directory fallback: do not stage or commit — return which # were applied or skipped and which files changed

After each wave: orchestrator reviews diffs (scope = assigned # only), runs tests (requires_verification: true on any applied finding → at least targeted tests; multi-file → broader suite), commits (fix(review): apply findings #…) unless worktree-isolated subagents merge per Phase 1. Repeat until all batches complete.

Optional inline shortcut (skip subagent spawn)

Use only when all of the following hold:

• Exactly one eligible finding after JSON filtering, and
• The orchestrator already has that file's relevant region in context from Phase 2 work this session (no new Read/Grep expedition)

Otherwise dispatch a subagent — even for a single finding. When unsure, dispatch.

Summary (required)

Report: batches dispatched, # applied vs skipped (with reasons from subagents), artifact path, tests run.

Handoff to Residual Work Gate

Any actionable finding not applied in this pass is residual work — proceed to the Residual Work Gate with an updated count. Do not re-invoke ce-code-review solely to re-apply the same findings unless the diff changed materially after fixes.

Shipping Workflow

This file contains the shipping workflow (Phase 3-4). It is loaded when all Phase 2 tasks are complete and execution transitions to quality check.

Phase 3: Quality Check

1. Run Core Quality Checks

Always run before submitting:

   # Run full test suite (use project's test command)
   # Examples: bin/rails test, npm test, pytest, go test, etc.

   # Run linting (per the project's configured lint command / active instructions)
   # Use linting-agent before pushing to origin

2. Simplify (conditional — separate from code review tiers)

Before code review, invoke `ce-simplify-code` when the diff is non-mechanical and large enough to benefit (default: >=30 changed lines). Skip when the diff is purely mechanical (formatting, dependency bumps, lint-only fixes, generated artifacts).

This step refines reuse, quality, and efficiency on the current diff so any later review sees cleaner code. It is not a substitute for Tier 1 or Tier 2 review.

Pass plan:<path> or a scope hint when the plan or user narrowed what changed. If the skill is unavailable on the harness, skip or do a brief manual pass for obvious duplicate/dead code — do not escalate to Tier 2 because simplify was skipped.

3. Code Review

Use Tier 1 when the harness provides a built-in review. Use Tier 2 only when escalation criteria below match — not because Tier 1 is missing.

Tier 1 -- harness-native review (default when available). Run the harness built-in code review (e.g., /review in Claude Code). Address blocking and suggested findings inline before Final Validation. Skip the Residual Work Gate.

Tier 2 -- `ce-code-review` (escalation only). Two steps — review is not fix.

2a. Review (read-only). Invoke ce-code-review with mode:agent (and plan:<path> when known; add base:<ref> when the diff base is already resolved). Parse JSON or Actionable Findings. Do not pass mode:autofix.

2b. Apply fixes (caller-owned). Load references/review-findings-followup.md: filter on JSON, batch by file, dispatch fix subagents. Orchestrator merges, tests, commits. Then proceed to the Residual Work Gate.

When Tier 1 is unavailable and Tier 2 criteria are not met: skip a dedicated review step. Phase 2 testing, simplify (when run), lint, and Final Validation still apply. Note in the shipping summary: Code review: skipped (no Tier 1 tool; Tier 2 criteria not met).

Escalate to Tier 2 when any of the following is true:

• Sensitive surface touched. The diff modifies any of: authentication or authorization, payments or billing, data migrations or backfills, cryptography or secret handling, security-relevant configuration, public API or library contracts, or dependency manifests.
• Large and diffuse change. The diff exceeds >=400 changed lines and spans more than 3 directories or 2 distinct subsystems. Either alone is a soft signal; together they are an escalation trigger.
• Very large change. The diff exceeds >=1,000 changed lines regardless of diffusion.
• Plan or task explicitly requests it. The plan, the originating task, or another instruction in scope calls for a full / deep / thorough code review.

When the change is small, concentrated, and outside the sensitive surface list, Tier 1 is sufficient -- do not escalate "to be safe."

4. Residual Work Gate (REQUIRED when Tier 2 ran)

After Tier 2 code review and review-findings followup, inspect the Actionable Findings summary (or read the run artifact at /tmp/compound-engineering/ce-code-review/<run-id>/ if the summary was truncated). If one or more actionable downstream-resolver findings were not applied in followup, do not proceed to Final Validation until the user decides how to handle them.

Ask the user using the platform's blocking question tool (AskUserQuestion in Claude Code with ToolSearch select:AskUserQuestion pre-loaded if needed, request_user_input in Codex, ask_question in Antigravity CLI (agy), ask_user in Pi (requires the pi-ask-user extension)). Fall back to numbered options in chat only when the harness genuinely lacks a blocking tool. Never silently skip the gate.

Stem: Code review left N actionable finding(s) not yet fixed. How should the agent proceed?

Options (four or fewer, self-contained labels):

• Apply/fix now — load references/review-findings-followup.md, dispatch batched fix subagents for remaining eligible findings, run tests, commit if needed; optionally re-run ce-code-review only after the diff changed materially.
• File tickets via project tracker — load references/tracker-defer.md in Interactive mode; the agent files tickets in the project's detected tracker (or gh fallback, or leaves them in the report if no sink exists) and proceeds to Final Validation.
• Accept and proceed — record the residual findings verbatim in a durable "Known Residuals" sink before shipping. If a PR will be created or updated in Phase 4, include them in the PR description's "Known Residuals" section (the agent owns this when calling ce-commit-push-pr). If the user later chooses the no-PR ce-commit path, create docs/residual-review-findings/<branch-or-head-sha>.md, include the accepted findings and source review-run context, stage it with the implementation commit, and mention the file path in the final summary. The user has acknowledged the risk, but the findings must not live only in the transient session.
• Stop — do not ship — abort the shipping workflow. The user will handle findings manually before re-invoking.

Skip this gate entirely when the review reported Actionable findings: none. (and followup applied everything mechanical) or when only Tier 1 was used. Do not proceed past this gate on an Accept and proceed decision until the agent has recorded whether the durable sink is PR Known Residuals or docs/residual-review-findings/<branch-or-head-sha>.md.

5. Final Validation

• All tasks marked completed
• Testing addressed -- tests pass and new/changed behavior has corresponding test coverage (or an explicit justification for why tests are not needed)
• Linting passes
• Code follows existing patterns
• Figma designs match (if applicable)
• No console errors or warnings
• If the plan has a Requirements section (or legacy Requirements Trace), verify each requirement is satisfied by the completed work
• If any Deferred to Implementation questions were noted, confirm they were resolved during execution

6. Prepare Operational Validation Plan (REQUIRED)

• Add a ## Post-Deploy Monitoring & Validation section to the PR description for every change.
• Include concrete:
• Log queries/search terms
• Metrics or dashboards to watch
• Expected healthy signals
• Failure signals and rollback/mitigation trigger
• Validation window and owner
• If there is truly no production/runtime impact, still include the section with: No additional operational monitoring required and a one-line reason.

Phase 4: Ship It

1. Prepare Validation Context

Do not try to launch a dedicated CE evidence-capture workflow. Modern harnesses provide their own browser, screenshot, terminal recording, and artifact capture tools; use those directly only when the user asks or when the artifact already exists.

Note whether the completed work has observable behavior (UI rendering, CLI output, API/library behavior with a runnable example, generated artifacts, or workflow output), and summarize any manual validation performed. If the user supplied evidence (URL, markdown embed, local artifact path), pass it to ce-commit-push-pr as PR-description context.

2. Commit and Create Pull Request

Load the ce-commit-push-pr skill to handle committing, pushing, and PR creation. The skill handles convention detection, branch safety, logical commit splitting, adaptive PR descriptions, and attribution badges.

When providing context for the PR description, include:

• The plan's summary and key decisions
• Testing notes (tests added/modified, manual testing performed)
• Evidence context from step 1, so ce-commit-push-pr can decide whether to ask about capturing evidence
• Figma design link (if applicable)
• The Post-Deploy Monitoring & Validation section (see Phase 3 Step 6)
• Any "Known Residuals" accepted in the Phase 3 Residual Work Gate, rendered as a dedicated section in the PR body with severity, file:line, and title per finding

If the user prefers to commit without creating a PR, load the ce-commit skill instead.

3. Notify User

• Summarize what was completed
• Link to PR (if one was created)
• Note any follow-up work needed
• Suggest next steps if applicable

Quality Checklist

Before creating PR, verify:

• [ ] All clarifying questions asked and answered
• [ ] All tasks marked completed
• [ ] Testing addressed -- tests pass AND new/changed behavior has corresponding test coverage (or an explicit justification for why tests are not needed)
• [ ] Linting passes (use linting-agent)
• [ ] Code follows existing patterns
• [ ] Figma designs match implementation (if applicable)
• [ ] Validation/evidence context passed to ce-commit-push-pr when the change has observable behavior
• [ ] Commit messages follow conventional format
• [ ] PR description includes Post-Deploy Monitoring & Validation section (or explicit no-impact rationale)
• [ ] Simplify: ce-simplify-code when diff >=30 lines (or skipped with reason)
• [ ] Code review: Tier 1 completed, or Tier 2 when escalated, or skipped (no Tier 1 + Tier 2 criteria not met — note in summary)
• [ ] PR description includes summary, testing notes, and evidence when captured
• [ ] PR description includes Compound Engineered badge with accurate model and harness

Code Review Tiers

Tier 1 when the harness has built-in review. Tier 2 (ce-code-review + followup) only when escalation criteria match — missing Tier 1 is not a reason to escalate.

Tier 1 -- harness-native review. Built-in command or skill (e.g., /review). Fix findings inline.

Tier 2 -- `ce-code-review` (escalation). (2a) Review-only via mode:agent. (2b) Batched fix subagents per references/review-findings-followup.md; residuals → Residual Work Gate.

Skip dedicated review when no Tier 1 and Tier 2 criteria not met (document in summary).

Escalate to Tier 2 when any of these holds:

• Sensitive surface touched (auth/authz, payments/billing, data migrations or backfills, cryptography or secrets, security-relevant config, public API or library contracts, dependency manifests)
• Large and diffuse change (>=400 changed lines AND >3 directories or 2 subsystems)
• Very large change (>=1,000 changed lines)
• Plan or task explicitly requests a full / deep / thorough code review

Tracker Detection and Defer Execution

This reference covers how residual actionable findings are filed in the project's tracker. Loaded by caller workflows (for example ce-work Residual Work Gate, or lfg residual handling) — not by ce-code-review, which stops after the report.

---

Execution Modes

Tracker-defer has two execution modes. The caller selects one; the detection, fallback chain, and ticket composition are shared.

Interactive mode

Used by ce-work Residual Work Gate and similar caller flows when the user chooses to file tickets. All user-facing prompts fire:

• First Defer of the session with a generic (non-named) label confirms the effective tracker choice.
• Execution failures prompt with Retry / Fall back to next sink / Convert to Skip.
• Labels in the routing question reflect named_sink_available (name the tracker) vs fallback generics.

Non-interactive mode

Used by autonomous callers like lfg that must not prompt. All blocking questions are skipped; the fallback chain is executed silently in order. Behavior:

• No confirmation on the first generic-label Defer; proceed directly.
• On execution failure, automatically fall to the next tier without prompting. Record the failure.
• On total chain exhaustion (every tier failed or no sink available), return findings in the no_sink bucket so the caller can route them to another surface (e.g., inline them in a PR description).
• Return a structured result: { filed: [{ finding_id, tracker, url }], failed: [{ finding_id, tracker, reason }], no_sink: [{ finding_id, title, severity, file, line }] }.

The caller decides how to surface the result to the user. The non-interactive mode treats "no sink available" as a data-producing outcome, not a prompt trigger.

---

Detection

The agent determines the project's tracker from whatever documentation is obvious. Primary source: the project's active instructions and conventions already in its context — no need to open or name specific instruction files. Read a file directly only when the relevant instructions aren't already in context: a subdirectory-scoped instruction file governing the area you're working in, or when you're a fresh subagent that wasn't given the project's instructions. Supplementary signals (when primary documentation is ambiguous): CONTRIBUTING.md, README.md, PR templates under .github/, visible tracker URLs in the repo.

A tracker can be surfaced via MCP tool (e.g., a Linear MCP server), CLI (e.g., gh), or direct API. All are acceptable. The detection output is a tuple with two availability flags — one for the named tracker specifically (drives label confidence in Interactive mode) and one for the full fallback chain (drives whether Defer is offered at all):

{ tracker_name, confidence, named_sink_available, any_sink_available }

Where:

• tracker_name — human-readable name ("Linear", "GitHub Issues", "Jira"), or null when detection cannot identify a specific tracker
• confidence — high when the tracker is named explicitly in documentation (or via a linked URL to a specific project/workspace) and is unambiguously the project's canonical tracker; low when the signal is thin, conflicting, or implied only
• named_sink_available — true only when the agent can actually invoke the detected tracker (MCP tool is loaded, CLI is authenticated, or API credentials are in environment); false when the tracker is documented but no tool reaches it, or when no tracker is found at all. Drives label confidence: inline tracker naming requires this to be true.
• any_sink_available — true when any tier in the fallback chain (named tracker or GitHub Issues via gh) can be invoked this session. Drives whether Defer is offered in Interactive mode, and drives the no_sink bucket in Non-interactive mode.

Detection is reasoning-based. Do not maintain an enumerated checklist of files to read. Read the obvious sources and form a confident conclusion; when the obvious sources don't resolve, the label falls back to generic wording and the agent confirms with the user before executing (Interactive mode only).

---

Probe timing and caching

Availability probes run at most once per session and only when Defer execution is imminent. Never speculatively at review start, never per-Defer, never per-walk-through-finding. The cached tuple is reused for every Defer action in the same run.

Typical probe sequence:

1. Consult the project's instructions already in context for tracker references — don't open or name specific instruction files; read one directly only when the relevant instructions aren't in context (subdirectory scope, or a fresh subagent). If nothing found, set tracker_name = null, confidence = low. 2. Probe the named tracker when one was found. For GitHub Issues, run gh auth status and gh repo view --json hasIssuesEnabled. For Linear or other connector/MCP-backed trackers, first discover available tools via the platform's tool-discovery primitive (e.g., ToolSearch in Claude Code) rather than assuming absence from an unloaded tool, then verify the discovered tool is responsive. For API-backed trackers, verify credentials wherever the platform exposes them (environment, connector auth, or a documented secrets location) — not only shell env vars. Set named_sink_available from the probe result. 3. Probe the GitHub Issues fallback to compute `any_sink_available`. Even when the named tracker was found and probed, gh matters for the no_sink bucket decision so that a run with no documented tracker but working gh still offers Defer.

• If named_sink_available = true: any_sink_available = true (no further probes needed).
• Otherwise, probe GitHub Issues via gh auth status + gh repo view --json hasIssuesEnabled (skip if already probed in step 2). If it works, any_sink_available = true.
• Otherwise, any_sink_available = false.

When Interactive mode's routing question is skipped entirely (R2 zero-findings case), no probes run. When the cached tuple is reused across a session, any named_sink_available = true from the session's first probe stays cached — do not re-probe per Defer.

---

Label logic (Interactive mode)

• When confidence = high AND named_sink_available = true: the routing question's option C and the walk-through's per-finding Defer option both include the tracker name verbatim. Example: File a Linear ticket per finding, Defer — file a Linear ticket.
• When any_sink_available = true but either confidence = low or named_sink_available = false (a fallback tier is working instead): the labels read generically — File an issue per finding, Defer — file a ticket. Before executing the first Defer of the session, the agent confirms the effective tracker choice with the user using the platform's blocking question tool.
• When any_sink_available = false: option C is omitted from the routing question, option B (Defer) is omitted from the walk-through per-finding options, and the agent tells the user why in the routing question's stem.

Non-interactive mode skips label decisions entirely — it acts silently on the detected sink.

---

Fallback chain

When the named tracker is unavailable or no tracker is named, fall back in this order. Prefer the project's detected tracker; use gh only when no named tracker was found or the named one is unreachable.

1. Named tracker (MCP tool, CLI, or API the agent can invoke directly, identified via Detection above) 2. GitHub Issues via `gh` — when gh auth status succeeds and the current repo has issues enabled (gh repo view --json hasIssuesEnabled returns true) 3. No sink — findings remain in the review report's residual-work section (Interactive mode) or are returned in the no_sink bucket for the caller to route (Non-interactive mode). The agent does not re-display them through a transient surface.

Previously this chain included a third in-session fallback tier. That tier was removed because in-session tasks do not survive past the session and therefore do not meet the "durable filing" intent of a Defer action. When no durable tracker exists, the correct behavior is to leave findings in the report (Interactive) or return them to the caller (Non-interactive).

---

Ticket composition

Every Defer action creates a ticket with the following content, adapted to the tracker's capabilities:

• Title: the merged finding's title (schema-capped at 10 words).
• Body:
• Plain-English problem statement — reads the persona-produced why_it_matters from the contributing reviewer's artifact file at /tmp/compound-engineering/ce-code-review/<run-id>/{reviewer}.json, using the same file + line_bucket(line, +/-3) + normalize(title) matching agent mode uses (see SKILL.md Stage 6 detail enrichment). Falls back to the merged finding's title, severity, file, and suggested_fix (when present) when no artifact match is available — these fields are guaranteed in the merge-tier compact return.
• Suggested fix (when present in the finding's suggested_fix).
• Evidence (direct quotes from the reviewer's artifact).
• Metadata block: Severity: <level>, Confidence: <score>, Reviewer(s): <list>, Finding ID: <fingerprint>.
• Labels (when the tracker supports labels): severity tag (P0, P1, P2, P3) and, when the tracker convention supports it, a category label sourced from the reviewer name.
• Length cap: when the composed body would exceed a tracker's body length limit, truncate with ... (continued in ce-code-review run artifact: /tmp/compound-engineering/ce-code-review/<run-id>/) and include the finding_id in both the truncated body and the metadata block so the artifact is discoverable.

The finding_id is a stable fingerprint composed as normalize(file) + line_bucket(line, +/-3) + normalize(title) — the same fingerprint used by the merge pipeline.

---

Failure path

When ticket creation fails at execution (API error, auth expiry mid-session, rate limit, malformed body rejected, 4xx/5xx response):

Interactive mode: surface the failure inline and ask the user using the platform's blocking question tool.

Stem:

Defer failed: <tracker name> returned <error summary>. How should the agent handle this finding?

Options:

• Retry on <tracker> — re-attempt the same tracker once more (useful for transient errors)
• Fall back to next sink — move this finding's Defer to the next tier in the fallback chain (e.g., from Linear to GitHub Issues)
• Convert to Skip — record the failure — abandon this Defer, note the failure in the completion report's failure section, and continue the walk-through or bulk flow

Non-interactive mode: do not prompt. Automatically fall through to the next tier. If every tier fails, record the finding in the failed bucket of the structured return and continue. If the chain exhausts with no sink ever available, the finding ends up in the no_sink bucket.

When a high-confidence named tracker fails at execution, the cached named_sink_available is set to false for the rest of the session. Subsequent Defer actions fall straight through to the next tier without retrying a confirmed-broken sink. any_sink_available is only downgraded to false when every tier has been confirmed broken — a failed Linear call that succeeds via gh keeps any_sink_available = true.

Only when ToolSearch explicitly returns no match or the tool call errors — or on a platform with no blocking question tool — fall back to numbered options and waiting for the user's reply (Interactive mode only).

---

Per-tracker behavior

Concrete behavior per tracker at execution time. The agent may invoke any of these through the appropriate interface (MCP, CLI, or API) — the choice depends on what is available in the current environment.

When uncertain, prefer "drop with explicit user-facing notice" over "pass through silently and hope." A Defer that produces no durable artifact and no user message is data loss.

---

Cross-platform notes

The question-tool name varies by platform. In Interactive mode, use the platform's blocking question tool (AskUserQuestion in Claude Code, request_user_input in Codex, ask_question in Antigravity CLI (agy), ask_user in Pi (requires the pi-ask-user extension)). In Claude Code the tool should already be loaded from the Interactive-mode pre-load step — if it isn't, call ToolSearch with query select:AskUserQuestion now. Fall back to numbered options in chat only when the harness genuinely lacks a blocking tool — ToolSearch returns no match, the tool call explicitly fails, or the runtime mode does not expose it (e.g., Codex edit modes without request_user_input). A pending schema load is not a fallback trigger. Never silently skip the question.

Non-interactive mode is platform-agnostic: it never prompts, so the platform's question tool is not relevant.