technical-debt

Files (1)

• SKILL.md

SKILL.md (first lines)

# Technical Debt Processing

Use this workflow when `/process-debt` is invoked or when asked to process recorded debt.

## 1. Read context

Read, in order:

- `AGENTS.md`
- `reports/tech-debt.md`
- relevant source files and tests
- `reports/registry.md`
- `openspec/AGENTS.md` and `openspec/config.yaml` when proposing a change

Run `git status --short` before changing files.

## 2. Classify every open item

For each open debt item, record:

- ID and source report
- affected files
- user/developer impact
- risk of a direct fix
- dependencies on other debt
- whether an OpenSpec change is required

A quick win must be:

- small and localized
- behaviorally clear
- low-risk
- independently testable
- not a schema, API, auth, synchronization, migration, or architecture change
- implementable without changing stated requirements

Examples of quick wins include missing tests, isolated validation, documentation, lint fixes, and small defensive fixes.

## 3. Process quick wins

For each approved quick win:

1. Add or update tests first where practical.
2. Implement the direct fix.
3. Run:
   ```bash
   uv run ruff check app tests
   uv run pytest --cov=app --cov-report=term-missing -q
   ```
4. Require total coverage to remain at least 85%.
5. Mark the debt item resolved in `reports/tech-debt.md`, preserving its source and resolution date.
6. Add a concise entry to `reports/registry.md` if a report or meaningful fix was produced.

Do not create an OpenSpec change for a qualifying quick win.

## 4. If no quick wins are suitable

Select the highest-value related open items by considering:

1. Critical/security/data-integrity impact
2. Blocking future synchronization or migration work
3. Number of related items that can be solved together
4. User impact and risk reduction
5. Implementation feasibility

Bundle related items into one OpenSpec proposal. Do not create multiple overlapping proposals.

Use:

```bash
openspec new change <kebab-case-name>
```

Then complete the `spec-driven` artifacts in order:

```text
proposal → specs → design → tasks
```

The proposal must include:

- bundled debt IDs and source reports
- motivation and measurable value
- scope and non-goals
- migration and rollback strategy
- external-integration compatibility impact
- security/reliability considerations
- test and coverage plan

Validate the proposal before finishing:

```bash
openspec status <change>
openspec validate <change>
```

Do not implement the proposal unless the user separately asks to apply it.

## 5. Final report

Summarize:

- debt items reviewed
- quick wins fixed and tests added
- remaining debt
- proposal created, if any
- verification results and final coverage

From spitoglou/pi-project-workflows, MIT.

More from spitoglou/pi-project-workflows