implement-task

Files (1)

• SKILL.md

SKILL.md (first lines)

# implement-task

Implement changes so they are correct, reviewable, and maintainable. Optimize for small safe increments, clear ownership, explicit validation, and low future change cost.

Treat `PLAN.md` as a contract. Do not improvise around it silently.

## Read first

- `../references/task-packet-contract.md`
- `../references/persistent-artifacts-contract.md`
- `../references/review-phases-contract.md`
- `../references/compatibility-policy.md`
- `../references/ownership-and-reuse-policy.md`
- `../references/final-state-authoring-policy.md`
- `../references/initiative-workflow-contract.md` when implementing an initiative child packet
- `../../references/communication-mode.md`
- relevant tracked `AGENTS.md` chain
- applicable `AGENTS.override.md` only if local execution constraints matter
- current task packet: `INDEX.md`, `PLAN.md`, `AMENDMENTS.md`, `ARTIFACT_CANDIDATES.md`

## Implementation workflow

1. Establish scope before coding.
   - Confirm the task, desired behavior, constraints, and nearby boundaries.
   - Refuse to start without `PLAN.md`.
   - Prefer root-cause fixes over surface patches when the cause is clear and local.
2. Repair packet drift before coding.
   - If `AMENDMENTS.md` or `ARTIFACT_CANDIDATES.md` is missing, create the missing placeholder before continuing.
   - Note the packet repair in `INDEX.md`.
3. Identify the true change surface.
   - Find the owner modules, contracts, state transitions, persistence paths, tests, and tracked `AGENTS.md` constraints that define the behavior.
   - Distinguish direct edits from incidental neighbors.
   - Distinguish internal boundaries from real external contracts relative to the service.
   - Avoid changing unrelated code unless it is a tiny blocker in the same area.
4. Apply ownership-and-reuse policy.
   - Identify the existing owner for each important behavior or invariant before adding code.
   - Prefer reusing, extending, or slightly refactoring that owner over creating a parallel helper/service/adapter/store/module/type.
   - If existing code is close but awkward, do a small tidy-first refactor that makes reuse possible.
   - Do not keep old and new same-purpose implementations alive together.
   - If a genuinely new boundary is required, make the non-overlapping responsibility explicit in code and packet notes.
5. Apply the compatibility policy.
   - Backward compatibility is prohibited by default.
   - Do not add aliases, shims, dual support, fallback behavior, or compatibility wrappers unless the human explicitly required compatibility.
   - If the change touches a real external boundary and compatibility requirements are unresolved, stop and ask the human explicitly before proceeding.
   - For internal-only changes, do not ask and do not preserve compatibility.
6. Implement the chosen target state directly.
   - Move canonical code/docs/contracts toward the steady-state design described in the plan.
   - Remove superseded vocabulary and same-purpose residue inside owner artifacts instead of layering new semantics on top of old names.
   - If a real external boundary requires temporary compatibility behavior, keep the steady-state owner and current contract obvious.
7. Implement in reviewable increments.
   - Follow the plan strictly.
   - Keep the system coherent after each step where possible.
   - Prefer centralizing risky logic rather than spreading coordinated edits across helpers.
   - Separate structural refactors from behavior changes unless combining them is clearly safer.
8. Preserve maintainability while coding.
   - Keep ownership obvious.
   - Minimize new sources of truth.
   - Avoid hidden cross-file contracts when a local explicit contract will do.
   - Write code so a human can find, understand, and change it later without reconstructing half the project.
   - Keep canonical owner artifacts in one vocabulary and one state model.
9. Validate deliberately.
   - Start with the smallest test or check that proves the changed behavior.
   - Expand validation as confidence grows.
   - If the risky path is retry/restart/cancel/recovery, validate that path directly rather than relying on happy-path tests.
10. Hand off cleanly.
   - Keep `AMENDMENTS.md`, `ARTIFACT_CANDIDATES.md`, and `INDEX.md` current enough that both review phases can start cold.
   - Record durable residue candidates when they appear.
   - Commit the implementation pass before reporting back to the lead.
   - Never write tracked `AGENTS.md` or `AGENTS.override.md` directly.

## Plan adherence rule

- Never silently deviate from the agreed plan.
- Unauthorized backward-compatibility work counts as plan drift unless the plan or later human amendment required it explicitly.
- A new same-purpose entity that the plan did not explicitly justify also counts as plan drift.
- Leaving canonical code/docs/contracts in a visible old-plus-new hybrid shape also counts as plan drift when the target design is already known.
- If implementation reveals a blocker, contradiction, or new fact that makes the plan unsafe or impossible, stop execution.
- Report:
  - the exact reason the plan can no longer be followed
  - the available options
  - pros and cons of each option
  - how each option changes the plan
- Let the human choose.
- After the human decides, update `AMENDMENTS.md` before continuing implementation.

## Suboptimal plan rule

- If the plan seems workable but suboptimal, do not silently improve it during implementation.
- Stay on plan.
- Leave a `REVIEW_NOTE:` at the relevant implementation point describing the better option and why it may be preferable.
- Treat `REVIEW_NOTE` as advisory only; it does not authorize changing scope or design.

## Implementation principles

- Make the safest next edit obvious.
- Prefer local reasoning over clever indirection.
- Keep risky logic centralized.
- Leave the code easier to review than before.
- Make canonical owner artifacts read like the current system, not like notes about an in-progress migration.
- Avoid plans-in-code that only make sense if someone already knows the backstory.
- Prefer tidy-first reuse over greenfield duplication.
- Keep one authoritative implementation path per important behavior whenever possible.

## When to slow down

Pause and think harder when:

- the task changes persistence or state ownership
- restart, retry, cancellation, or recovery semantics are involved
- the change introduces a second source of truth
- the easy fix requires scattered coordinated edits
- a test passes, but does not actually prove the risky behavior
- the real code shape disagrees with the plan
- a better design appears mid-implementation but was not approved in the plan
- you are about to add a new same-purpose entity because the current owner is inconvenient to reuse

## Initiative child packets
For initiative-created child packets:
- stop immediately if `PLAN.md` still says `Status: not_authored`

From siarhei-belavus/agent-public, MIT.

More from siarhei-belavus/agent-public