spae-fix

Files (5)

• SKILL.md
• STATE.md · references/
• cleanup-guide.md · references/
• shell-command-guide.md · references/
• testing-guide.md · references/

SKILL.md (first lines)

# Fix (`SPAE`)

## When to use

- `STATE.json` reports `phase: fix`.
- `FIX.md` lists pre-classified gaps for the active in-progress task.

## Goal

- Close only the active task's named `FIX.md` gaps through minimal,
  test-driven changes.
- Return the _workstream_ to `/check` without task completion, cursor
  movement, plan edits, or scope expansion.

## Input

Read:

- _STATE.json_ in `.spae/current/` for task management (consult
  `references/STATE.md` for field reference, directives, and phase
  snapshots).
- _FIX.md_ in `.spae/current/` for gaps to address.
- Project source, tests, configuration, docs, and command output
  required by the named gaps.

## Testing

See `references/testing-guide.md` for test structure, isolation,
mocking, assertion, and performance standards.

## Cleanup

See `references/cleanup-guide.md` for the self-introduced-artifact
checklist and diff-only audit scope.

## Workflow

1. **GATE**—Read `.spae/current/STATE.json`; confirm `phase: fix` and an
   active task identifier. Self-heal metadata: inject missing `version`
   (`"1.0"`), `workstream` (from symlink or directory path), and
   `status` (`"active"`). Self-heal state drift: if
   `tasks[`active_task_id`]` reads `"todo"` or lacks an entry, set it to
   `"in_progress"` and write `STATE.json` before proceeding. Halt on
   state drift: if `tasks[`active_task_id`]` reads `"done"`, halt. Read
   `.spae/current/FIX.md`; confirm its task identifier matches the
   active task and its `## Gaps` list supplies concrete actionable gaps.
   Halt on _unparseable_ JSON, unrecognized phase, missing `FIX.md`, or
   mismatched task identifier; report the failed precondition; make no
   changes.
2. **ORIENT**—Goal: close the named gaps for one active task and return
   it to `/check`. Leave task completion, cursor movement, forward
   tasks, and unrelated project concerns untouched. Capture pre-task
   baseline snapshot per `references/cleanup-guide.md`.
3. **PLAN**—List each pre-classified `FIX.md` gap. Map its required test
   surface: expected behavior, failure modes, and edge cases. Use the
   task `Intent` only for context; never expand scope from it,
   `Acceptance`, `Verification`, forward tasks, seams, or observations.
4. **ACT**—For each named gap:
   - Write a failing or gap-reproducing test covering expected behavior,
     failure modes, and edge cases.
   - Write the minimal source, test, configuration, or documentation
     change required by that gap.
   - Run targeted checks; repeat `test→implement` until the gap passes.

   Ignore `Observations` for source changes. Stop after every listed gap
   has passing test coverage. Never write production code before its
   test exists.

5. **VERIFY**—Loop over every named gap and its relevant project checks:
   - Audit changed tests for project CI parity; correct violations.
   - Audit task edits against the pre-task baseline using the
     Self-cleanup checklist in `references/cleanup-guide.md`; remove
     every self-introduced artifact before proceeding.
   - For each unmet gap or failing check: return to **ACT**, remediate,
     then re-enter **VERIFY**.
   - Exit only after every gap test and relevant task check passes.
   - Fail the task only for an infeasible finding, plan or spec defect,
     or broken external dependency. Leave `FIX.md` and state transition
     untouched.
6. **PERSIST**—After every named gap passes, delete
   `.spae/current/FIX.md` and write `.spae/current/STATE.json` once with
   `phase: check`. Keep the active task `in_progress`; never mark it
   `done` or alter the cursor. Re-read `STATE.json` after writing; on a
   field mismatch, rewrite and re-read before `REPORT`.
7. **REPORT**—Emit the result under Result directives. After successful
   remediation, use guide template C verbatim. On a failure, report it
   under Findings and never claim gap closure.

## Directives

- Optimize work for agent, token, and context efficiency.
- Consult `references/shell-command-guide.md` for command safety,
  timeouts, redirects, and non-interactive environment directives.
- Consult `references/cleanup-guide.md` for self-introduced-artifact
  scope, baseline snapshotting, and checklist directives.
- Follow canonical _SPAE_ Step 6 `/fix` whenever guidance conflicts.
- Remediate exactly one active task per invocation.
- Scope every change solely from `FIX.md` `## Gaps`; consume those
  pre-classified gaps as written.
- Treat `Observations` as informational only; never classify, promote,
  or act on them.
- Prefer existing project patterns; apply _KISS_ and _YAGNI_.
- Drive every listed gap through test→*implement*; treat red checks as
  ordinary remediation work.
- Hold exclusive authority for source edits during `/fix`, limited to
  files required by named gaps.
- Never inspect forward tasks or preserve forward seams; remediation
  closes named gaps only.
- When closing a named gap invalidates an existing test's now-incorrect
  expectation, update that test to match; make no other contract change
  beyond what the named gap requires; never weaken, skip, or delete
  tests to force green.

## Constraints

- May edit source, tests, documentation, configuration, and other
  _non-SPAE_ project files only when named gaps require them; never
  delete pre-existing uncommitted files or edit outside active-task
  scope.

From mystilleef/spae-framework, MIT.

More from mystilleef/spae-framework