implementation-strategy

name	implementation-strategy
description	Decide the compatibility boundary and implementation approach before changing runtime behavior, shared types, task state transitions, or HTTP/gRPC contracts. Use this before risky refactors or contract changes.
owner	any
trigger	null
version	1

Implementation Strategy

Use this before changing any interface or shared behavioral contract that other code depends on.

When To Use

• Editing shared types, enums, or message payloads in crates/swx-core/**
• Changing task-state transitions, gate behavior, or conductor orchestration
• Changing HTTP or gRPC request/response shapes in crates/swxd/**
• Refactoring shared dashboard hooks, API client contracts, or cross-view data flow
• Any change where "works locally" is weaker than "remains compatible"

Workflow

1. Identify the change surface. Write down the files, exported types, states, endpoints, or cross-module contracts that will change.
2. Classify compatibility risk. Use safe, caution, or breaking.
3. Choose the implementation shape first. Prefer compatibility shims, additive changes, and conductor-owned orchestration over direct replacement.
4. Define the verification surface. List the tests and runtime paths that must stay green.
5. Only then edit code.

Platform-Specific Checks

• If you touch TaskState, review valid transitions in crates/swx-core/src/task.rs.
• If you touch conductor orchestration, check restart/recovery ownership in crates/swx-actors/src/conductor.rs and crates/swx-actors/src/recovery.rs.
• If you touch task control APIs, keep state mutation in the conductor, not in swxd handlers.
• If you touch dashboard query wiring, keep query keys, invalidation, and mutation status centralized in existing hooks before adding new one-off behavior.

Output Format

implementation_strategy:
  change_surface:
    - file: "path/to/file"
      contract: "what other code depends on"
      risk: "safe|caution|breaking"
  approach:
    - "planned implementation step"
  verification:
    - "tests and checks to run"
  main_risks:
    - "specific regression risk"

Keep it short. The point is to force a compatibility decision before editing.