papi-sdlc-fix

Files (2)

• SKILL.md
• fix-task-template.md · assets/

SKILL.md (first lines)

# SDLC Task - Fix

- Read, copy and use the template.

## When to use this skill

Use this skill whenever a defect, bug, or unintended behaviour is being
addressed as a task, regardless of whether the defect is in code, a
specification, documentation, tooling, or a process.

## Dependencies

Reading these skills is REQUIRED to understand and execute this skill:

- PAPI skill `papi-sdlc-understand`
- PAPI skill `papi-tasks-understand`
- PAPI skill `papi-templates-understand`

## Core principles

### Fix + improve

A defect fix task is not a minimal patch. It is an opportunity to leave the
affected area in a better state than before the defect was introduced. Every
fix task MUST consider and, where feasible, incorporate:

1. **Root cause addressed** — not just the symptom. Document the root cause
   explicitly; if it cannot be fixed in this task, record it as a follow-on.

2. **Clarity improvement** — if the defect caused confusion (e.g., ambiguous
   naming, missing documentation, unhelpful error messages, misleading
   descriptions), improve the relevant artefact so the same confusion cannot
   recur. This applies equally to code interfaces, specification language,
   process descriptions, and user-facing copy.

3. **Consistency improvement** — if the defect reveals an inconsistency across
   related artefacts (e.g., naming conventions, structural patterns, response
   contracts, formatting), address the inconsistency as part of the task, not
   just the specific broken instance.

4. **Eliminate unnecessary extra steps** — if the defect forced users or
   callers to perform an additional action to obtain information or state that
   should have been available in the first place, fix the artefact so that
   extra step is no longer needed.

5. **Artefacts in sync** — every fix that changes observable behaviour or
   structure **must** update all affected artefacts: specification, code,
   tests, and documentation. A fix without corresponding artefact updates is
   incomplete.

### Scope discipline

"Leave it better" does not mean "also fix everything else you notice".
Improvements included in a fix task must be:
- **Directly related** to the defect or its root cause.
- **Bounded** — if an improvement is significant enough to risk scope creep,
  create a separate task and note it as a follow-on.

### Evidence first

Before writing the plan, capture the exact observed behaviour as evidence.
This serves as the acceptance test: the fix is done when the evidence
condition no longer occurs.

### Test-Driven Development

Use proper TDD: write a failing test that directly captures the observed
evidence, then implement the fix to make that test pass. This ensures the
fix is verifiable and prevents regressions.

## Skill artefacts

- **Template**: `assets/fix-task-template.md`

From stainsby/papi, MIT.

More from stainsby/papi