nicolas-codemate/resolve

Resolve - Modular Workflow Orchestrator

<context> This skill orchestrates the complete ticket resolution workflow by loading and executing individual step files. Each step is a separate file containing focused instructions, loaded only when needed to minimize context usage. </context>

Input

Arguments passed from command: $ARGUMENTS

Step 1: Parse Arguments

<instructions> Extract from arguments: - `ticket_id`: Optional (see Step 1.5 for resolution) - Flags: `--init`, `--auto`, `--continue`, `--refine-plan`, `--plan-only` - Options: `--source`, `--target`, `--skip-simplify`, `--skip-review`, `--skip-visual-verify`, `--pr`, `--draft`, `--no-draft`, `--wait-for-ci` (optional integer, default 3) </instructions>

Step 1.5: Resolve Ticket ID (if not provided)

<ticket_resolution> If ticket_id is NOT provided in arguments (and NOT --init mode):

1. List existing feature directories

ls -1 .claude-work/ 2>/dev/null || echo ""

2. Handle based on mode and results

| Mode | 0 tickets | 1 ticket | Multiple tickets | |------|-----------|----------|------------------| | AUTO | ERROR: "Aucun ticket en cours. Specifiez un ticket-id." | Use that ticket automatically | ERROR: "Plusieurs tickets en cours: {list}. Specifiez le ticket-id." | | INTERACTIVE | Prompt for ticket ID | Ask to confirm or enter different | Ask user to choose from list |

3. INTERACTIVE - No tickets found

AskUserQuestion:
  questions:
    - question: "Aucun ticket en cours. Quel ticket voulez-vous traiter ?"
      header: "Ticket"
      multiSelect: false
      options:
        - label: "Saisir le ticket ID"
          description: "Entrer manuellement le numero de ticket"

4. INTERACTIVE - One ticket found

AskUserQuestion:
  questions:
    - question: "Ticket en cours detecte: {ticket-id}. Continuer avec celui-ci ?"
      header: "Ticket"
      multiSelect: false
      options:
        - label: "Oui, continuer avec {ticket-id}"
          description: "Reprendre le workflow existant"
        - label: "Non, autre ticket"
          description: "Saisir un autre ticket ID"

5. INTERACTIVE - Multiple tickets found

AskUserQuestion:
  questions:
    - question: "Plusieurs tickets en cours. Lequel traiter ?"
      header: "Ticket"
      multiSelect: false
      options:
        - label: "{ticket-1}"
          description: "State: {state from status.json}"
        - label: "{ticket-2}"
          description: "State: {state from status.json}"
        # ... up to 4 options, then "Autre" for more

</ticket_resolution>

Step 1.6: Rename the Session

<instructions> Once `ticket_id` is known (skip in `--init` mode when no ticket is given), rename the session so it can be found later in `/resume`:

~/.claude/scripts/rename-session.sh "resolve-{ticket-id}"

Step 01 refines this title with the ticket title once it is fetched. This step exists because CONTINUE and REFINE modes never run step 01.

If the script fails, note it and continue — renaming never blocks the workflow. </instructions>

Step 2: Determine Mode

<mode_detection> | Flag | Mode | Starting Step | |-------------------|-------------|--------------------------| | --init | INIT | 00-initialization (config only) | | --continue | CONTINUE | 06-implement | | --refine-plan | REFINE | 05-plan-validation | | --auto | AUTO | 00-initialization | | (default) | INTERACTIVE | 00-initialization | </mode_detection>

Step 3: Load Current Step

<workflow> 1. Check mode to determine starting point 2. If CONTINUE or REFINE: - Read status from `.claude-work/{ticket-id}/status.json` (where ticket-id comes from arguments) - Verify status.json exists and is valid (ERROR if not found) - Load ticket context and plan from `.claude-work/{ticket-id}/` 3. Read step file: `${CLAUDE_SKILL_DIR}/steps/{step-number}-{step-name}.md` - **Replace check**: if `local_steps` (in status.json) has an entry with `replace` matching this step id, execute the project file instead of the step's own instructions. The original step's `## Transition` section still decides what comes next. 4. Execute step instructions: - **INLINE steps**: Execute directly in main thread - **DELEGATED steps**: Follow Orchestration section (gather params, launch Agent, verify) 5. **After check**: execute every `local_steps` entry whose `after` matches the step that just completed, in config order (see Local Steps section) 6. Follow the step's `## Transition` section to load and execute the next step 7. **Repeat steps 3-6** until a step says STOP or workflow is complete

Implementation (step 06) is not the end. The full AUTO sequence is: 06-implement → 07-simplify → 08-review → 08b-spinoffs → 09-finalize Each step's Transition section tells you exactly which step file to load next. </workflow>

<critical_paths> Feature directory structure — all workflow files are stored in .claude-work/{ticket-id}/:

• status.json - Workflow state and options
• ticket.md - Ticket content
• plan.md - Implementation plan
• implementation-notes.md - Running notes maintained during step 06: design decisions, deviations, tradeoffs, open questions. Surfaced in INTERACTIVE mode after each phase, displayed in full at the end (step 09).
• spin-offs.md - Follow-up work found during steps 06, 07 and 08 but out of this ticket's scope. Decided on at step 08b, then surfaced in the PR body and the final recap. Format: ~/.claude/skills/resolve/references/spin-offs.md.

The resolve directory (.claude-work) is configurable via feature_dir in ticket-config.json.

Do not use docs/ for workflow files — always .claude-work/{ticket-id}/. </critical_paths>

<base_branch_rule> Base branch usage — all git diff operations should use the base branch from status.json:

# Read base branch from status
BASE_BRANCH=$(cat .claude-work/{ticket-id}/status.json | jq -r '.options.base_branch')

# Use it in all diff operations
git diff ${BASE_BRANCH}...HEAD
git diff --name-only ${BASE_BRANCH}...HEAD

Do not hardcode main, master, or develop in git diff commands. Do not use HEAD~1 to detect changes — always compare against the base branch.

Base Branch Lifecycle:

1. Step 00 (initialization): Initial detection (may default to main)
2. Step 01 (fetch-ticket): Update base_branch from the ticket's milestone/target
   • YouTrack: Extract from "Milestone" field (e.g., "2025-12-continue" → branch "2025-12")
   • GitHub: Extract from milestone or base branch if PR
3. Steps 02+: Use updated base_branch from status.json

The ticket's milestone takes precedence over default detection. </base_branch_rule>

Step Execution Flow

<step_flow>

Standard Flow (INTERACTIVE)

00-initialization → 01-fetch-ticket [AGENT] → 02-analyze-complexity
→ 03-exploration [AGENT] → 04-create-plan [AGENT] → 05-plan-validation
→ 06-implement [AGENT] → 07-simplify [AGENT] → 08-review [AGENT] → 08b-spinoffs → 09-finalize
                    |                                                    ^
                    +-- /resolve --continue -----------------------------+

Standard Flow (AUTO)

00-initialization → 01-fetch-ticket [AGENT] → 02-analyze-complexity
→ 03-exploration [AGENT] → 04-create-plan [AGENT] → 05-plan-validation
→ 06-implement [AGENT] → 07-simplify [AGENT] → 08-review [AGENT] → 08b-spinoffs → 09-finalize

CONTINUE Flow

(verify status) → 06-implement [AGENT] → 07-simplify [AGENT] → 08-review [AGENT] → 08b-spinoffs → 09-finalize

08b-spinoffs runs before finalize because the PR body cites the ticket numbers it opens. It is skipped when spinoffs.collect = false, and opens nothing when spinoffs.allow_creation = false — in that case it only reports.

REFINE Flow

(load context) → 05-plan-validation (refine loop) → 06-implement [AGENT] → ...

INIT Flow

00-initialization (config only) → STOP

PLAN-ONLY Flow

00-initialization → ... → 05-plan-validation → STOP (display plan + next steps)

</step_flow>

Delegation Architecture

<delegation> Heavy steps are delegated to subagents with fresh context (~200K tokens). The main thread stays lightweight, preserving context for orchestration and user interaction.

Model Selection by Complexity

Subagent model and effort are determined by complexity (stored in status.json as model_config):

| Complexity | Model | Effort | Rationale | |------------|-------|--------|-----------| | SIMPLE | sonnet | medium | Cost-efficient for trivial changes | | MEDIUM | opus | high | Full reasoning for multi-component work | | COMPLEX | opus | max | Deepest reasoning, no token constraints (Opus 4.6 only) |

The model parameter is passed to all delegated agents (steps 03, 04, 06, 07). Step 08 (review) always uses opus via the code-reviewer agent definition. The effort level applies to the main orchestrator session (set via /effort or status context).

| Step | Execution | Reason | |------|-----------|--------| | 00-initialization | INLINE | Lightweight config | | 01-fetch-ticket | DELEGATED | MCP responses (YouTrack, Figma) consume context | | 02-analyze-complexity | INLINE | Lightweight scoring | | 03-exploration | DELEGATED | Already uses Explore agents | | 04-create-plan | DELEGATED | Reads ticket.md + analysis.md, generates plan | | 05-plan-validation | INLINE | User interaction must stay in main thread | | 06-implement | DELEGATED | Biggest context consumer - fresh context is critical | | 07-simplify | DELEGATED | Invokes bundled /simplify skill (multi-angle technical review with auto-applied fixes) | | 08-review | DELEGATED | Product-fit review via code-reviewer agent (ticket coverage, acceptance criteria) | | 08b-spinoffs | INLINE | Decides on follow-up tickets — creation must stay under the user's eye | | 09-finalize | INLINE | Lightweight git push + PR |

Delegated step pattern: Each delegated step file has two sections:

1. Orchestration (main thread): gather params, launch Agent, verify completion
2. Execution (subagent prompt): full instructions passed to the agent

This eliminates the need for /compact or session breaks between planning and implementation. </delegation>

Local Steps (project-provided)

<local_steps> Projects can insert or replace workflow steps via local_steps in .claude/ticket-config.json:

{
  "local_steps": [
    { "after": "07-simplify", "file": ".claude/resolve-steps/review-custom.md" },
    { "replace": "08-review", "file": ".claude/resolve-steps/product-review.md" }
  ]
}

Each entry has exactly one anchor (after or replace, value = a main step id like 07-simplify), a project-relative file, and an optional execution (delegated by default, or inline).

Semantics:

• after: X — runs right after step X completes, before X's Transition is followed. Multiple entries on the same anchor run in config order.
• replace: X — the project file is executed instead of step X's own instructions. The original step X's ## Transition section still governs the next step, and after: X entries still fire (the replacement counts as X).
• Natural skip: if a step never executes (skip flag, mode path, STOP before it), its after and replace entries never execute either. There is no dedicated skip flag for local steps — e.g. --skip-review also skips anything anchored to 08-review.
• After a local step completes, record it in status.json under phases with key local:{filename} — this is what makes resume idempotent.

Local steps are read from status.json (persisted at step 00 so CONTINUE mode sees them). If local_steps is absent from status.json (workflow started before this feature), read .claude/ticket-config.json directly.

Authoring contract for project step files: see ~/.claude/skills/resolve/references/local-steps.md. </local_steps>

Mode Reference

See ~/.claude/skills/resolve/references/modes.md for detailed mode behaviors.

Coding Guidelines (mandatory)

See ~/.claude/skills/resolve/references/coding-guidelines.md for the three non-negotiable principles applied during implement (06): reuse before creating, readability over cleverness, comment frugality.

Step 07 (simplify) delegates to the bundled /simplify skill, which uses its own technical review taxonomy and does NOT read this file — accept that trade-off in exchange for broader multi-angle coverage. Step 08 (review) is scoped to product fit only and does not enforce these technical principles either; they are enforced upstream at implementation time and at the simplify pass.

Step Files

| Step | File | Description | |------|------|-------------| | 00 | steps/00-initialization.md | Setup, config loading, feature directory | | 01 | steps/01-fetch-ticket.md | Retrieve ticket, extract Figma URLs, user context | | 02 | steps/02-analyze-complexity.md | Score complexity, determine workflow type | | 03 | steps/03-exploration.md | Explore codebase based on complexity | | 04 | steps/04-create-plan.md | Generate implementation plan | | 05 | steps/05-plan-validation.md | Validate/refine plan interactively | | 06 | steps/06-implement.md | Execute plan, visual verification | | 07 | steps/07-simplify.md | Technical review + simplification via bundled /simplify | | 08 | steps/08-review.md | Product-fit review (ticket coverage + acceptance criteria) | | 08b | steps/08b-spinoffs.md | Dedup the collected follow-ups, open tickets if the project allows it | | 09 | steps/09-finalize.md | Push and create PR |

Error Handling

<constraints> - If step file not found: ERROR with clear message - If a `local_steps` entry references a missing file or an unknown step id: ERROR at initialization, before any work starts - If status.json invalid for CONTINUE: ERROR "Plan not validated" - If ticket not found: ERROR with troubleshooting hints - Always update status.json after each step completion </constraints>

Language

All user communication in French. Technical output (git, code, files) in English.

NOW

<instructions> 1. Parse the arguments provided 2. Determine the execution mode 3. Load and execute the appropriate starting step 4. Follow the step's `next` directive until STOP or completion </instructions>

Begin workflow for: $ARGUMENTS