---
name: scratchpad
description:
  "Use a repo-local .scratchpad as uncommitted short-term memory for active research, planning,
  Markdown backlogs, handoff files written by the handoff skill, references, and cross-session
  coordination. Use to inspect, initialize, organize, reconcile, archive, or extract Scratchpad
  context while keeping current code, Git state, tests, tracked documentation, and live evidence
  authoritative."
argument-hint: "[status | explore | init | backlog | sync | reconcile | archive | extract]"
---

# Scratchpad

Use `.scratchpad` to preserve active context across sessions and compactions. Treat it as useful but
disposable working memory, not as proof that work landed.

## Routing

The modes below are modes of this skill, not shell commands. `.scratchpad` is a folder of Markdown
and this skill is what operates on it — do not shell out to run a mode.

If `$ARGUMENTS` contains an explicit mode, go directly to its action:

- `status` — report the current Scratchpad inventory without editing it.
- `explore` — map relevant contents and reconcile material claims with current evidence.
- `init` — create or organize a useful repo-local Scratchpad.
- `backlog` — materialize, validate, or update Markdown issues and milestones using the backlog
  contract.
- `sync` or `reconcile` — reconcile active files with current truth, then update or archive them.
- `archive` — archive specified inactive material and repair indexes.
- `extract` — promote stable facts into durable tracked locations.

Otherwise infer the action from the request and current Scratchpad state. Preserve `sync` as an
alias for `reconcile`; do not require callers to change existing invocations.

## Coordinate parallel work

For multi-worktree or multi-harness work:

1. Choose one canonical `.scratchpad`, normally in the primary checkout, and record its absolute
   path in the root index and relevant handoffs.
2. Use one coordinator for shared indexes, milestone state, and cross-lane reconciliation.
3. Give each autonomous delivery lane the absolute canonical Scratchpad root plus a write allowlist
   containing only its owning issue and/or one lane-specific tracker. The worker records its own
   commits, PR, hosted/reviewed SHAs, validation, review state, and blockers directly there; it
   never creates a worktree-local evidence copy.
4. Never assign two writers to the same Scratchpad file. The coordinator reconciles worker evidence
   into shared milestones and indexes instead of relaying every lane transition.
5. Record lane, workspace, session, assigned work, write allowlist, and last-known state in a
   coordination note.
6. Confirm canonical evidence and reconcile shared milestone state before releasing the worker lease
   or removing its worktree.

For durable user-visible tasks, the coordinator owns one Markdown-table registry at
`.scratchpad/backlog/handoffs/task-registry.md`; it records the stable task ID/title, stream,
current delivery, worktree/branch/PR, last verified base, next-ready work, exclusions, and write
allowlist. Treat the registry as a recovery aid: task runtime, Git, GitHub, tests, and providers
remain authoritative.

Treat coordination notes as advisory. Recheck actual worker, Git, and runtime state before assigning
or closing work.

## Truth boundary

Current code, tests, tracked documentation, Git state, and live evidence are authoritative for
implementation and runtime claims. Scratchpad files preserve intent, research, plans, decisions, and
continuity; they may be incomplete or stale. Record every mismatch and update, archive, or mark the
stale claim — but never implement or reopen work solely because an old note says it remains
unfinished.

Do not stage or commit `.scratchpad` by default. Verify rather than assume its ignore behavior:

```bash
git check-ignore -v .scratchpad/README.md 2>/dev/null || true
git status --short -- .scratchpad
```

## Suggested structure

Create only the directories the project needs:

```text
.scratchpad/
├── README.md
├── research/
├── backlog/
│   ├── issues/
│   ├── milestones/
│   ├── handoffs/
│   └── parking-lot.md
├── reference/
└── archive/
```

- Keep `README.md` as a small index of active work and important continuity pointers.
- Put investigations, comparisons, and temporary findings in `research/`.
- Put executable work and delivery groupings in `backlog/`.
- Put session-continuity artifacts in `backlog/handoffs/`.
- Put unsettled working contracts in `reference/`.
- Move inactive working memory into date-prefixed `archive/` folders.

This is a convention, not a required schema. Follow an existing repository layout instead of
rewriting it to match this example.

## Inspect and explore

Current Scratchpad state; preloaded in Claude Code, run yourself in other harnesses:

- Scratchpad tree: !`ls -la .scratchpad 2>/dev/null | head -30`
- Recent Scratchpad files: !`fd . .scratchpad -t f 2>/dev/null | head -30`

Start with a bounded inventory:

```bash
git status --short --branch
fd . .scratchpad -t f 2>/dev/null | sort
```

Read `README.md` first, then only the relevant active files; do not load the archive by default.

For each material claim, capture:

- the claim and source file;
- the current code, Git, test, or runtime evidence;
- whether the claim is current, partial, stale, superseded, or unverified;
- the exact remaining gap, if one exists.

## Status

Report without editing:

- files, last-modified times, and age;
- active research, backlog, reference, handoff, and archive areas;
- root-index presence and broken pointers;
- obvious stale-state risks that need reconciliation.

For a large tree, split the inventory into bounded, non-overlapping areas. Keep the same output
contract when parallel workers are unavailable.

## Initialize

For a repository without a Scratchpad, create a minimal `README.md` and only the folders needed for
the current work. The root index should explain:

- what is active;
- where the current plan or backlog lives;
- where the latest handoff lives;
- which checkout or worktree owns shared coordination state.

Do not create placeholder files or elaborate taxonomy without an immediate use.

For an existing flat or inconsistent Scratchpad:

1. Inventory every active file and the pointers to it.
2. Check related code, Git history, branches, PRs, tests, and runtime evidence where relevant.
3. Classify each file as active research, backlog, handoff, reference, archive, or temporary noise.
4. Move files only after establishing their current role; preserve useful history.
5. Rebuild the root index around active files and record why archived material moved.

## Markdown backlogs

Read [references/backlog-contract.md](references/backlog-contract.md) when materializing,
validating, or updating issues and milestones. This skill owns backlog representation and lifecycle;
workflows such as `discovery` and `delivery` supply approved content and execution evidence.

Validate the materialized graph with:

```bash
uv run scripts/validate_backlog.py
```

Follow a stronger repository convention when one exists; do not bulk-migrate or invalidate existing
Markdown-only files merely to match the default contract.

For research, reference, handoff, and archive documents, use lightweight `status`, `updated`,
`supersedes`, or `replaced_by` fields only when useful; do not impose the backlog schema.

## Reconcile

Reconcile before resuming a plan or reporting status:

1. Read the root index and relevant active files.
2. Capture current branch, worktrees, commits, dirty files, tests, and relevant runtime state.
3. Compare Scratchpad claims with current evidence.
4. Mark each active item `keep`, `update`, `archive`, or `defer`.
5. Update partial work honestly; do not mark work complete without observable evidence.
6. Refresh root-index pointers and remove dead links.

Before editing, summarize the evidence and proposed verdicts:

```text
| File | Scratchpad claim | Current evidence | Verdict |
|------|------------------|------------------|---------|
| ...  | ...              | ...              | keep / update / archive / defer |
```

Then execute the verdicts: update partial or stale claims, archive completed context, move genuinely
deferred work to the repository's parking-lot convention, and leave current material in place. Fix
affected indexes and links in the same pass. Age is only a review signal — old research may still be
relevant and recent notes may already be superseded.

## Archive

Archive material when it is no longer active but remains useful for context. Prefer a date-prefixed
folder with a short note explaining why it was archived, what replaced or completed it, and where
durable conclusions now live. Delete only obvious temporary noise.

## Extract durable truth

Move stable implementation facts, invariants, operational procedures, and architectural decisions
into tracked documentation, specifications, code comments, tests, or ADRs. Cite the implementation
paths that support the claim and distinguish landed behavior from known gaps. Update the existing
document that already owns the topic instead of creating a new one; use an ADR when the durable
artifact is a decision and its rationale, not a description of current implementation.

Keep planning rationale, temporary research, active issues, and session handoffs in `.scratchpad`.
Link the durable destination from the Scratchpad source before archiving it.

## QA sessions

Treat QA sessions as research work units:

- keep a session active while findings remain untriaged;
- move actionable findings into backlog issues before archiving the session;
- keep unacted findings in research rather than silently treating them as complete;
- link archived sessions to the resulting issues, fixes, or durable documentation.

## Completion checks

Before finishing Scratchpad work, verify that the root index points only to active existing files,
that partial, stale, and superseded work is labeled honestly, and that `.scratchpad` remains
unstaged unless the user explicitly requested otherwise.