Three-Phase Workflow

Use this skill as a defensive change-control workflow. Its purpose is to prevent local fixes from creating upstream or downstream bugs.

Core principle: slow is fast. Do not optimize for moving to implementation quickly; optimize for proving the change surface, business invariant, and verification path before editing.

Every user-facing reply must start with the current stage declaration.

The workflow is user-gated. Completing a stage is not permission to continue. The user must explicitly approve the next stage before the assistant enters it.

When there is any uncertainty, ambiguity, weak evidence, missing context, competing interpretation, or even a small concern, ask the user directly before proceeding. Do not silently make assumptions in this workflow.

Stage 0: Research-Grounded Change Surface Scan

Declaration format: 【Stage 0: Research-Grounded Change Surface Scan】

Use Stage 0 before Stage 1 for any new task unless the task is a tiny non-development question.

Stage 0 is not a quick classification step. It is a lightweight investigation phase that prevents premature narrowing. Do not declare a request "frontend-only", "backend-only", "copy-only", or "safe" until you have inspected enough product context and code evidence to justify that boundary.

Required actions

• Run a PRD-style clarification pass before finalizing the change surface:
  • problem or goal
  • core behavior expected by the user
  • explicit non-goals
  • success criteria
  • existing codebase or new work
  • data model or external data shape
  • business rules, calculations, and edge cases
  • quality gates
• Ask clarifying questions in Stage 0 when the request can plausibly have more than one business interpretation. Prefer 3-7 focused questions for broad or semantic changes.
• Ask the user about any small uncertainty instead of resolving it by assumption.
• Perform a minimum code reconnaissance before classifying the change:
  • locate the user-facing entry point
  • locate the API/client mapping
  • locate the backend/service owner if data is involved
  • locate data source, configuration, reference inputs, dependency capabilities, or constants when behavior, calculations, labels, or outputs are involved
  • when a label, field, output, or derived value changes meaning, trace both the produced value path and every supporting input path before suggesting any implementation direction
  • locate at least one focused test that asserts the current behavior
• State what evidence was inspected and what evidence is still missing.
• Classify the change surface:
  • calculation semantics
  • API fields or contracts
  • labels, units, or displayed meaning
  • data source or reference/supporting inputs
  • configuration or feature flags
  • persistence schema or migration
  • compatibility or old callers
  • tests, docs, deployment, or operations
• Identify whether the request may be breaking:
  • field deletion or rename
  • unit change
  • label change
  • response shape change
  • behavior change for existing data
  • migration from hardcoded logic to configurable logic
• State the business invariant that must remain true.
  • For calculations, verify that quantity, price, unit, date, benchmark, and display label describe the same business entity.
  • For APIs, verify that producers, consumers, old bundles, external callers, and docs agree on the contract.
• Identify semantic prerequisites. If the requested meaning requires a new data source, reference input, transformation rule, unit conversion, schema field, external feed, business configuration, model capability, permission, integration, or operational process that does not exist yet, name that missing prerequisite and include "add the missing prerequisite first" as a candidate solution.
• Decide which upstream and downstream links must be inspected before planning.

Minimum evidence table

For semantic, calculation, field, unit, label, or API changes, Stage 0 must include a compact evidence table with at least:

• affected concept or field
• current known source
• current known meaning
• supporting inputs or reference data, if any
• suspected downstream consumers
• confidence level
• unknowns that must be resolved in Stage 1

Use "unknown" honestly when Stage 0 reconnaissance is insufficient. Unknowns should drive the Stage 1 investigation list.

Absolutely forbidden

• Do not classify a change as frontend-only only because the visible request mentions a page, label, or table header.
• Do not classify a change as backend-only only because the requested fix lives in a service.
• Do not conclude that business logic is unchanged until source data, API mapping, and display semantics have been sampled.
• Do not propose changing labels, fields, outputs, or derived values into a new semantic meaning unless the required supporting inputs, transformations, capabilities, and validation path are known or explicitly proposed as prerequisites.
• Do not silently choose "preserve old semantics" when the user is asking for a new semantic meaning; surface both the old-semantic option and the "add missing prerequisites first" option.
• Do not ask for Stage 1 approval before listing the reconnaissance evidence and open questions.

Exit gate

End Stage 0 by asking the user whether to enter Stage 1. Do not enter Stage 1 until:

• the change surface and business invariant are explicit
• reconnaissance evidence and unknowns are listed
• the Stage 1 investigation targets are listed
• the user explicitly approves Stage 1

Stage 1: Analyze the Problem

Declaration format: 【Stage 1: Analyze the Problem】

Stage 1 is evidence gathering. Do not edit files.

Required actions

• Deeply understand the core requirement and the user's stated goal.
• Inspect code one relevant fragment at a time instead of relying on keyword-level conclusions.
• Produce an evidence table for every key field, metric, API response, label, unit, and benchmark touched by the change. The table must include source, meaning, unit, upstream producer, downstream consumers, and current test coverage.
• Trace the full upstream and downstream chain when the change touches behavior:
  • source data
  • configuration
  • parsing and normalization
  • calculation logic
  • reference/supporting inputs
  • persistence and cache
  • API contract
  • frontend mapping and display
  • old callers, external callers, gray release, and compatibility
  • tests
  • docs
• Identify root cause and distinguish it from symptoms.
• Surface architectural issues, duplicated logic, hidden contracts, and semantic mismatches.
• Look for existing working patterns in the codebase before proposing a new pattern.
• Ask for missing information only when it cannot be discovered locally and a wrong assumption would materially affect the result.
• Ask the user about any unresolved doubt, however small, before recommending a solution.
• Ask at least one explicit confirmation question before leaving Stage 1 unless the analysis proves there is only one safe, non-breaking interpretation.
• Provide 1-3 viable solutions that do not conflict with the user's goals.
• Evaluate pros, cons, compatibility impact, migration risk, and verification cost for each solution.

Required proof for semantic changes

For calculation, field, label, unit, or API changes, explicitly answer:

• What does the field or metric mean before the change?
• What will it mean after the change?
• Which data source proves that meaning?
• Which supporting inputs, reference data, transformations, or capabilities are used?
• If the target meaning needs a new prerequisite, what must be added before the field, output, or behavior can honestly carry that meaning?
• Which callers consume it?
• What breaks if old and new versions run at the same time?
• Which tests prove business correctness, not only code execution?

Absolutely forbidden

• Modify code or docs.
• Recommend a solution without tracing the relevant chain.
• Treat a user-chosen direction as proof that the business invariant is valid.
• Use tests that only encode the proposed new behavior as evidence that the behavior is business-correct.

Exit gate

End Stage 1 by asking the user to choose a solution and approve Stage 2. Do not enter Stage 2 until:

• the full required chain is inspected, or every uninspected link is explicitly marked as a known blocker or accepted risk
• the evidence table is complete for semantic or contract changes
• the user explicitly chooses a solution
• the user explicitly approves Stage 2

Stage 2: Detail the Plan

Declaration format: 【Stage 2: Detail the Plan】

Stage 2 converts evidence into an implementation plan. Do not edit product code. The plan itself must be persisted before discussion continues.

Prerequisite

• The user has explicitly chosen a solution.
• The user has explicitly approved Stage 2.
• Stage 1 evidence supports the chosen solution.

Required actions

• At the very start of Stage 2, create .tasks/ if needed and write the plan to .tasks/<short-descriptive-name>.md.
• Choose a stable, descriptive, lowercase kebab-case filename based on the task, such as .tasks/benefit-summary-cu-p-split.md.
• Write the .tasks/*.md plan in Chinese unless the user explicitly requests another language.
• The task file must include:
  • problem statement
  • chosen solution
  • business invariant
  • evidence summary from Stage 1
  • files to change
  • upstream and downstream impacts
  • compatibility strategy
  • verification matrix
  • rollback or recovery notes
  • open questions
• Update the .tasks/ plan file whenever Stage 2 materially changes the plan.
• List files to add, modify, or delete and summarize each change.
• Describe complex logic using "Step 1, Step 2, ..." or another clear sequence.
• Define the business invariant that the implementation must preserve.
• List upstream and downstream effects for every changed contract, field, label, unit, or calculation.
• Define compatibility strategy:
  • compatible alias
  • migration window
  • old caller behavior
  • gray release behavior
  • removal plan, if removal is truly required
• Define verification matrix:
  • syntax or type checks
  • targeted unit tests
  • integration or API contract tests
  • frontend mapping or rendering tests
  • migration or cache checks
  • docs verification
  • manual or production-like smoke checks when needed
• Identify rollback or recovery path for risky changes.
• Ask concise confirmation questions for every critical implementation choice that could affect business semantics, compatibility, data correctness, or user-visible behavior.
• Ask the user about any remaining uncertainty before writing or updating the .tasks/ plan.

Absolutely forbidden

• Continue Stage 2 planning in chat only without first writing the .tasks/ plan file.
• Plan an ad-hoc or temporary solution unless the user explicitly chooses it after seeing the tradeoff.
• Omit compatibility analysis for breaking API, field, label, or unit changes.
• Treat "tests pass" as sufficient when the tests do not cover the business invariant.

Exit gate

End Stage 2 by asking the user to approve Stage 3. Do not enter Stage 3 until:

• the .tasks/ plan file exists and reflects the final plan
• the implementation plan, compatibility strategy, and verification matrix are explicit
• the user explicitly approves Stage 3

Stage 3: Execute the Plan

Declaration format: 【Stage 3: Execute the Plan】

Stage 3 is controlled implementation. Execute the chosen plan, but keep evaluating evidence.

Stage 3 requires explicit user approval from Stage 2. Never infer approval from the existence of a plan.

Required actions

• Implement strictly according to the approved plan.
• Keep edits scoped to the planned change surface.
• Preserve unrelated user or workspace changes.
• Update code, tests, docs, and callers together when the contract or behavior changes.
• Run the verification matrix from Stage 2 unless the environment blocks it.
• Report any blocked verification with the exact blocker and residual risk.
• Clean up obsolete tests, mocks, fields, and docs that the approved plan intentionally removes.

Mandatory rollback to Stage 1

Stop implementation and return to Stage 1 when new evidence shows any of these:

• The business invariant is broken or incomplete.
• Quantity, price, unit, date, benchmark, or label semantics do not match.
• An upstream or downstream link was missed.
• A breaking API or field change lacks a compatibility or migration plan.
• A test proves only the new implementation behavior, not the business correctness.
• The chosen plan conflicts with existing production data, old callers, gray release, or deployment constraints.
• A mirrored implementation, client, docs, or cache path has equivalent behavior that was not accounted for.

When rolling back, state the evidence that invalidated the plan and the next analysis target.

Absolutely forbidden

• Continue executing only because the user previously approved Stage 3 when new evidence invalidates the plan.
• Delete or rename public fields without an explicit compatibility strategy.
• Claim completion without running or reporting the planned verification.
• Commit code unless the user explicitly asks.

Phase Transition Rules

• Default stage for a new development or analysis task: Stage 0.
• Move from Stage 0 to Stage 1 only after the change surface and invariant are explicit and the user explicitly approves Stage 1.
• Move from Stage 1 to Stage 2 only after the relevant chain is inspected, a solution is chosen, and the user explicitly approves Stage 2.
• Move from Stage 2 to Stage 3 only after the .tasks/ plan file is written and the user explicitly approves Stage 3.
• Stage 3 may always return to Stage 1 when evidence invalidates the plan.
• Do not mix implementation with Stage 0, Stage 1, or Stage 2.
• Do not use phase rules as an excuse to ignore stronger safety evidence.
• Phrases such as "continue", "ok", "looks good", or "do it" count as stage approval only when they are responding directly to a stage-transition question. Otherwise ask a clarifying transition question.

Pre-Response Checklist

• Did the reply start with the current stage declaration?
• Is the response limited to the allowed work for that stage?
• For semantic or contract changes, is the business invariant explicit?
• For behavior changes, has the upstream/downstream chain been traced?
• For breaking changes, is compatibility or migration addressed?
• Did the user explicitly approve the current stage transition?
• If in Stage 2, has the plan been written to .tasks/<short-descriptive-name>.md before continuing?
• Did I ask the user about every uncertainty instead of assuming?
• If new evidence appeared, should the workflow roll back to Stage 1?