Stats
Actions
Tags
From finesse
Task-type-specific planning workflows for Finesse — defines phases for features, bug fixes, chores, testing, performance, and research work
How this skill is triggered — by the user, by Claude, or both
Slash command
/finesse:task-workflowsThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
After detecting the task type, follow the corresponding workflow below. Every workflow ends with plan construction, validation, pre-flight, and presentation. The phases before that differ by task type.
After detecting the task type, follow the corresponding workflow below. Every workflow ends with plan construction, validation, pre-flight, and presentation. The phases before that differ by task type.
Phases marked with [UAT] require a User Acceptance Testing checkpoint as defined in the main command (finesse.md). When you complete a [UAT] phase, follow the UAT Checkpoint Procedure before proceeding to the next phase.
If the user has elected to fast-forward UAT (by selecting "Accept and skip remaining UAT" at any checkpoint), skip the checkpoint and proceed directly. Discovery/Understanding phase confirmations are never affected by fast-forward.
Classify the user's task into one of these types based on their description:
| Type | Signals |
|---|---|
| feature | "Add", "build", "create", "implement", "new", introduces new functionality |
| bugfix | "Fix", "broken", "not working", "error", "crash", "wrong", "regression" |
| refactor | "Refactor", "clean up", "reorganize", "restructure", "improve code", "tech debt" |
| testing | "Add tests", "test coverage", "write tests", "validate", "QA" |
| performance | "Slow", "optimize", "performance", "speed up", "bottleneck", "latency" |
| research | "Research", "investigate", "compare", "evaluate", "analyze", "study", "survey", "document", "explore options", "understand", "assessment", "trade-offs", "pros and cons", "spike", "feasibility" |
If ambiguous, ask the user. Do not guess.
After exploration reveals codebase context but before architecture/strategy design, analyze whether the task should be decomposed into multiple independent sub-workflows that each run as a separate ralph-loop.
Propose splitting when ANY of these apply:
Do NOT decompose when:
| Task Type | Primary Metrics | Decomposition Signals |
|---|---|---|
| Feature | code complexity (files touched), independent concerns, integration points | >8 files, >2 independent concerns, >18 estimated iterations |
| Bugfix | triage effort (hypothesis count), multi-stage fixes, regression surface | >2 distinct root causes, fix spans >3 independent areas |
| Refactor | scope breadth (modules), dependency chain depth, migration stages | >3 modules, chain >4 deep, >2 migration stages |
| Testing | coverage breadth (areas), suite size, framework heterogeneity | >3 test areas, >25 test cases, >2 frameworks |
| Performance | bottleneck count, scope breadth, measurement independence | >2 independent bottlenecks, optimizations in >3 areas |
| Research | scoping breadth (topics), section count, investigation independence | >5 sections, >3 independent threads |
These templates define common patterns used across multiple workflows. Each task-type workflow references these and provides only its unique customization.
Every exploration/investigation phase follows this pattern:
.finesse/exploration-cache.json.Goal: Determine whether the task should be decomposed into multiple independent ralph-loop sub-workflows.
UAT topics: decomposition decision, sub-workflows (if any), dependency graph, impact on remaining phases
--max-iterations with reasoning using the task-type-specific iteration ranges listed in each workflow.Goal: Understand what needs to be built — thoroughly.
Do NOT proceed until the user confirms your understanding is correct. This is NOT a UAT checkpoint — Discovery requires iterative back-and-forth until alignment is achieved.
Goal: Understand relevant existing code and patterns.
Follow the Exploration Phase Template. Launch 2-3 code-explorer agents:
UAT topics: similar features found, architecture patterns and conventions, key files and responsibilities
Follow the Scope Analysis Phase Template using feature metrics.
Goal: Fill every gap before designing.
Based on codebase exploration, identify underspecified aspects:
Present ALL questions in an organized list. Wait for answers before proceeding.
Goal: Design multiple implementation approaches.
Launch 2-3 code-architect agents in parallel, each with a different focus:
UAT topics: each approach with architecture decisions, trade-offs, and verification strategy; your recommendation with reasoning
Note: When the user selects "Accept" at this checkpoint, ask which approach they are accepting (or if they accept your recommendation). When they select "Provide feedback" or "Make specific changes", the feedback may target a specific approach or request an entirely different direction.
Follow the Plan Construction Phase Template. Task-specific content:
UAT topics: complete prompt with cold start, phases, verification, guardrails, completion criteria; recommended iterations with reasoning
Launch all 6 validation agents in parallel on the drafted plan. Refine per severity tier rules in the prompt-validation skill.
After validation passes, run pre-flight checks per the "Pre-flight Validation" section of finesse.md Common Final Phases. Collect warnings for presentation.
Present the validated plan. On acceptance, save to finesse-plans/ and output the command.
Goal: Fully understand the bug before touching code.
Gather from the user:
If the user provides sparse information, ask explicitly for missing details. Do NOT proceed with partial understanding.
Do NOT proceed until you have a clear reproduction path. This is NOT a UAT checkpoint — Bug Understanding requires iterative back-and-forth until the reproduction path is clear.
Goal: Trace the bug through the code.
Follow the Exploration Phase Template. Launch 2 code-explorer agents:
After agents return, map the exact code path where the bug occurs.
UAT topics: exact code path where bug occurs, relevant files and functions, recent changes, related tests
Follow the Scope Analysis Phase Template using bugfix metrics.
Goal: Identify the actual root cause, not just symptoms.
Based on investigation:
If multiple possible causes, present them ranked by likelihood.
UAT topics: root cause hypothesis with evidence, error type, related bugs sharing the same root cause
Goal: Design the fix with regression prevention.
UAT topics: minimal fix, regression tests to add, existing tests to update, related code to check
Follow the Plan Construction Phase Template. Task-specific content:
Validate, run pre-flight checks, and present. Same as feature workflow phases 7-8.
Goal: Define exactly what's being refactored and why.
Clarify with the user:
If the user describes the refactor vaguely (e.g., "clean up the auth module"), ask: What specifically is wrong with it today? What does "clean" look like? What would success look like?
This is NOT a UAT checkpoint — Scope Definition requires iterative back-and-forth until the scope is clearly defined.
Goal: Map what exists before changing it.
Follow the Exploration Phase Template. Launch 1-2 code-explorer agents:
After agents return, build a dependency map.
UAT topics: all files involved, dependency map, callers, existing tests, breakage risks
Follow the Scope Analysis Phase Template using refactor metrics.
Goal: Define the end state concretely.
UAT topics: target architecture, file changes, dependency updates, breaking changes, migration path
Goal: Plan the safest path from current to target state.
Design an incremental migration that:
UAT topics: migration phases in order, verification at each step, revert strategy, caller update plan
Follow the Plan Construction Phase Template. Task-specific content:
Validate, run pre-flight checks, and present.
Goal: Understand what's tested and what isn't.
Follow the Exploration Phase Template. Launch 1-2 code-explorer agents:
Ask the user:
After gathering exploration results AND user answers, synthesize a coverage picture.
UAT topics: testing framework and conventions, coverage map, user's priority areas and coverage goals
Follow the Scope Analysis Phase Template using testing metrics.
Goal: Prioritize what to test and how.
Based on exploration:
UAT topics: untested paths ranked by risk, test types per area, shared utilities, mocking dependencies
Goal: Resolve testing-specific ambiguities.
Follow the Plan Construction Phase Template. Task-specific content:
Validate, run pre-flight checks, and present.
Goal: Define what's slow, how slow, and what's acceptable.
Clarify with the user:
Do not accept vague performance complaints. Insist on specifics: which operation, what latency, what is acceptable. This is NOT a UAT checkpoint — Problem Definition requires iterative back-and-forth until the performance target is concrete.
Goal: Find the actual bottleneck, don't guess.
Follow the Exploration Phase Template. Launch 1-2 code-explorer agents:
UAT topics: identified bottlenecks with evidence, existing optimization patterns, what the slow area is missing
Follow the Scope Analysis Phase Template using performance metrics.
Goal: Design the optimization with measurable targets.
UAT topics: optimization approaches with expected impact, measurable verification for each, risks and trade-offs
Follow the Plan Construction Phase Template. Task-specific content:
Validate, run pre-flight checks, and present.
Goal: Clarify what the research should answer and what the deliverable looks like.
Gather from the user:
Push back on overly broad research questions. A good research question has a clear "done" state.
Do NOT proceed until the research question is specific enough to have a clear "done" state. This is NOT a UAT checkpoint — Goal Definition requires iterative back-and-forth until the research question is sharp.
Goal: Map codebase sources, architecture, and prior decisions related to the research topic.
Follow the Exploration Phase Template. Launch 2-3 code-explorer agents:
After agents return, build a source inventory before proceeding.
UAT topics: sources found and relevance, prior decisions discovered, gaps needing external research
Follow the Scope Analysis Phase Template using research metrics.
Goal: Propose a research outline and resolve ambiguities before investigation begins.
Based on source identification, propose:
Present ALL clarifying questions:
Wait for the user to answer all clarifying questions. Then incorporate their answers into the research plan.
UAT topics: finalized outline with sections, depth per section, codebase vs external knowledge split
Goal: Define what to investigate for each section and how to verify findings.
For each section in the confirmed outline:
Key constraints:
UAT topics: per-section investigation plan, rabbit holes to avoid, constraints
Goal: Build the ralph-loop prompt with research-specific adaptations.
Follow the Plan Construction Phase Template. Task-specific content:
grep -c "^## " <deliverable> — section count matches outlinewc -w <deliverable> — minimum word count metgrep -c "TODO\|PLACEHOLDER\|TBD" <deliverable> — no placeholders remaingrep -c "file:.*line\|\.rb:\|\.ts:\|\.py:\|http" <deliverable> — evidence citations existgrep "^## <Section Name>" <deliverable>Launch all 6 validation agents in parallel on the drafted plan. Refine per severity tier rules in the prompt-validation skill.
After validation passes, run pre-flight checks per the "Pre-flight Validation" section of finesse.md Common Final Phases. Collect warnings for presentation.
Present the validated plan. On acceptance, save to finesse-plans/ and output the command.
When the Scope Analysis phase results in an accepted decomposition, the remaining workflow phases operate differently:
Shared phases: Discovery/Understanding, Exploration/Investigation, and Scope Analysis are shared across all sub-workflows. They run once and their outputs are included in every sub-workflow's prompt context.
Shared architecture: If the workflow includes an Architecture Design phase (Feature), architecture decisions are shared. The architect designs the overall system; decomposition determines which pieces each sub-workflow builds.
Per-sub-workflow phases: Only Plan Construction and Validation run independently for each sub-workflow. Each gets its own prompt, promise, and plan files.
Clarifying Questions: Run once with awareness of all sub-workflows. Questions may be sub-workflow-specific but are asked in a single batch.
Context budget: Each sub-workflow gets its own context budget estimate (since each runs in its own context window). If any sub-workflow exceeds critical pressure (>80%), the re-route fires for that specific sub-workflow. An aggregate summary of all sub-workflow budgets is included in execution-graph.md.
Validation: Each sub-workflow's prompt is validated independently by all 6 standard validation agents.
Presentation: All sub-workflows are presented together with the execution graph. The user accepts or rejects the entire decomposition as a unit.
Per-wave execution commands — The execution-graph.md file includes ready-to-run commands for each sub-workflow:
## Wave 1 (run in parallel)
/finesse:finesse-execute --prompt-file finesse-plans/<session>/wave-1/<task>/prompt.md --completion-promise-file finesse-plans/<session>/wave-1/<task>/promise.txt --max-iterations <N>
## Wave 2 (run after Wave 1 completes)
/finesse:finesse-execute --prompt-file finesse-plans/<session>/wave-2/<task>/prompt.md --completion-promise-file finesse-plans/<session>/wave-2/<task>/promise.txt --max-iterations <N>
npx claudepluginhub jonathanung/finesse --plugin finesseOrchestrates all code-modifying development tasks like bug fixes, enhancements, and new features using adaptive phases for analysis, specs, TDD, implementation, and verification.
Orchestrates development tasks that modify code—bug fixes, enhancements, new features—with adaptive phases for codebase analysis, specs, planning, implementation, and TDD testing.
Guides software development through six-phase workflow: Research, Plan, Iterate Plan, Experiment, Implement, Validate. Generates structured markdown docs via slash commands for auditable trails.