se-backlog

Files (1)

• SKILL.md

SKILL.md (first lines)

# Engineering Backlog

Maintain a durable, repo-local backlog for real engineering follow-up work that is useful but outside the current scope.

This is a **skill**, not a command-line interface. The user should not need to say `add`, `list`, `promote`, or remember subcommands. Infer the intent from the conversation and act naturally.

## Purpose

The backlog is the package's parking lot for actionable engineering work discovered during planning, debugging, implementation, review, or maintenance.

It exists to protect the rest of the SE workflow:

- Atomic commits stay focused because out-of-scope work is captured instead of smuggled into the current slice.
- Plans stay decision artifacts instead of growing miscellaneous todo sections.
- Strategy stays strategic instead of becoming a feature queue.
- Follow-up work survives context windows, branches, and sessions.

## Interaction Method

When asking the user a question, use the platform's blocking question tool: `AskUserQuestion` in Claude Code (call `ToolSearch` with `select:AskUserQuestion` first if its schema isn't loaded), `request_user_input` in Codex, `ask_user` in Gemini, `ask_user` in Pi (requires the `pi-ask-user` extension). Fall back to numbered options in chat only when no blocking tool exists in the harness or the call errors. Never silently skip the question.

Ask only when the item value, destination, duplicate handling, promotion target, or destructive prune action is ambiguous.

## Storage

Backlog state lives in two places that are kept in sync automatically:

1. **Pi session log** — per-session runtime substrate. Survives `/compact`, `/fork`, restart, and worktree changes.
2. **`work/items/parking-lot/<id>-<slug>.md` files on disk** — cross-session parking lot for ungraduated work. Every `backlog_add` / `backlog_promote` / `backlog_remove` writes/patches/deletes the matching file immediately. Items captured in one session are visible to another session reading the same repo without needing an explicit export.

| Tool | Purpose |
|---|---|
| `backlog_add` | Capture a new item. Appends a session-log entry AND writes `work/items/parking-lot/<id>-<slug>.md`. Mints a coordination-free time-sortable id; no counters. |
| `backlog_list` | List active parked items. Reads both the current session log and on-disk `work/items/parking-lot/` files; merges by id (session log wins for in-flight changes). |
| `backlog_promote` | Mark a parked item promoted to `se-work`, `se-plan`, `se-debug`, or `other`. Appends a promotion entry AND patches the parking-lot file's `status:` line to `In Progress`. Promotion records intent; the folder is born only when the first real artifact is written. |
| `backlog_remove` | Append a removal entry AND delete the parking-lot file. Use after ungraduated work lands or the user explicitly drops the item. |
| `backlog_export` | Bulk re-render active parked items to `work/items/parking-lot/<id>-<slug>.md`. Use after manually editing entries, after pulling from another machine, or to repair drift. Skips existing files unless `overwrite=true`. |

**Why disk sync.** The backlog is the one SE entry type whose value is durable, cross-session follow-up work. Without disk sync, items captured in session A are invisible to session B — which defeats the point. The per-mutation file write is the documented cost paid to deliver cross-session visibility. All other `se:*` state (phase, worktree, test-state, residuals, repro) stays session-log-only; the backlog is the exception, not the precedent.

**Working-tree churn.** Each park/promote/prune touches `work/items/parking-lot/*.md` and shows up as a working-tree change. This is intentional. If you want to suppress noise during an active slice, defer commits of parking-lot changes until you reach a natural checkpoint.

**Export target.** The export target is `work/items/parking-lot/` at the repository root. Do not export under `docs/` (durable knowledge) or `.context/software-engineering/` (local scratch).

**ID allocation.** `backlog_add` mints a fresh time-sortable id (ULID). There is no `.next-id`, no max-scan, and no counter to coordinate across worktrees. The id is stable from birth; filenames stay repo-portable: lowercase slug, no absolute paths.

**Migration from an existing on-disk backlog.** Legacy `backlog/task-NNN - *.md` files should be migrated once into `work/items/parking-lot/<id>-<slug>.md` with the old task id preserved as `legacy: task-NNN`. The live tools use the work layout; do not create new legacy backlog files.

## Item Format

Preserve an existing repo's backlog item format when one is present. For a new backlog, use this structure:

```md
---
id: 01KT7BEG3WWXEW1CNFD7MMK5GA
slug: short-action-oriented-title
origin: parked
title: Short action-oriented title
status: To Do
priority: medium
labels:
  - follow-up
created: YYYY-MM-DD
source: se-work | se-debug | se-code-review | se-plan | user | other
context:
  cwd: .
  branch: feat/example-branch
  commit: a1b2c3d
  repo: owner/name
  pi_session: 019e5d76-4269-727d-ad39-64a67e06a241
  invoked_by: se-debug
  issue_ref: "#123"
---

# Short action-oriented title

## Context

What was noticed, where it came from, and any relevant links/files/PRs.

## Why it matters

The cost, risk, user impact, or compounding value of doing this later.

## Acceptance Criteria

- [ ] Observable condition that proves the item is complete
- [ ] Test, doc, cleanup, or verification expectation when applicable

## Related

- `repo/relative/path.ext`
- PR/issue/session reference if known

## Notes

Additional investigation notes. Keep this short; promote to a plan when it grows.
```

## Intent Inference

Infer one of these intents from the user's language and the current SE workflow. Do not require the user to name a mode.

### Capture

Triggered by phrases like:

- "park this"
- "add this to the backlog"
- "save this for later"
- "put this in the bucket"
- "we should follow up on this"
- another skill finds real but out-of-scope work

Capture only if the item is actionable and worth preserving. If the value is unclear, ask one concise question: "Should I keep this as backlog follow-up or drop it?"

Do not capture:

- vague wishes with no action

From simonwjackson/pi-software-engineering, MIT.

More from simonwjackson/pi-software-engineering