reliquary/plugins/spire/skills/workpad/SKILL.md

---
name: workpad
description: Decides WHERE and WHEN to put working documents — reports, plans, goals, brainstorms, designs, journals, research, specs, tickets, bug notes. Use this skill whenever the user asks you to write a "report", "plan", "goal", "brainstorm", "design", "journal", "research note", "spec", or anything "in the workpad" — and also when another skill is about to drop a markdown file somewhere ad-hoc (e.g. a plugin's own `docs/<plugin>/` subdirectory, the repo root, `/tmp`, or alongside source code). If a workpad exists, the workpad wins. This skill steers other skills toward a single, predictable place for markdown documents, whichever plugin they come from.
---

# Workpad

The workpad is the user's filing cabinet for thinking-in-markdown. Reports, plans, brainstorms, post-mortems — anything that is *about* the work rather than *being* the work — lives here. This skill answers two questions only: **where** does a given document go, and **when** is one kind of document the right kind versus another. It does not tell you how to write the contents.

Treat this skill as authoritative for placement. If another skill suggests writing a markdown artifact to its own scratch directory (a plugin-named folder, a sibling `notes/` dir, the repo root, etc.), prefer the workpad instead. A single predictable location is more valuable than each skill having its own.

## Where the workpad lives

Resolve the workpad base directory in this order — stop at the first hit:

1. **Explicit user instruction in the current conversation.** If they said "put it in `~/notes/foo`", that wins.
2. **`WORKPAD_FOLDER` environment variable.** Reading it reliably is fiddly because Agents run commands in subshells that may not inherit the user's interactive env, and the value may be injected on purpose not available to the agent:
   - `just workpad-folder` (or any equivalent recipe) if a `.justfile` / `Justfile` is present and defines one — `just` loads `.env` automatically.
   - `printenv WORKPAD_FOLDER` as a last resort. This will only see values exported into the actual process environment.
   If any of these prints a non-empty path, treat it as the workpad base.
3. **Project-local tickets folder.** Some projects keep a sibling folder *outside* the main repo for per-ticket scratch (e.g. `../<repo>-tickets/` or a path configured via `GITEA_TICKETS_DIR`). If one is configured, the workpad base is `<tickets-folder>/workpad/` and individual ticket folders sit beside it as `<tickets-folder>/<id>/`. See "Ticket context" below for how those interact. When in doubt whether one exists, ask.
4. **`/docs/workpad`** at the project root, if a `/docs` folder already exists.
5. **`/.workpad`** at the project root.
6. **Otherwise: ask.** If there is no `/docs` folder and no other signal, do not silently create `/docs/workpad/`. Ask the user where the workpad should live, and confirm before creating any folders.

## Folder structure

The workpad always contains at least these subfolders:

- `brainstorm/` — open-ended exploration, options, half-formed ideas
- `goals/` — acceptance criteria, milestones, "what we're trying to reach"
- `designs/` — design docs, architecture sketches, RFC-style writeups
- `plans/` — concrete sequences of steps to execute
- `reports/` — findings, summaries, status writeups

It may also contain any of these, created on demand:

- `archive/` — superseded or completed material moved out of the way
- `bugs/` — bug investigations and notes
- `journals/` — append-only narratives of long-running problems
- `research/` — external research, library evaluations, prior art
- `specs/` — frozen, unchanging specifications
- `tickets/` — per-ticket scratch space, one subfolder per ticket id (see "Ticket context")
- `adepts/` — adept domain folders — see `spire:adepts`

If one of these optional folders is needed and doesn't exist yet, create it. Don't create folders speculatively. Treat unknown folders as owned by the user and ignore them.

## Ticket context

A **ticket folder** is `<workpad>/tickets/<id>/`, or `<tickets-folder>/<id>/` when the project configures an external tickets directory. It is created on demand once the id is known — no need to ask.

A ticket context is **active** when any of these holds:

- the user named the ticket for this session ("we're on #42", "start ticket 42", "this is for PROJ-17");
- a ticket skill opened or created the ticket folder earlier in this conversation;
- the user explicitly asked for a file to go into the ticket.

It is **not** active just because a ticket folder exists on disk, or the branch name contains a number. If the work smells ticket-shaped but nobody said so, ask once and stick with the answer. When several tickets have been mentioned, the most recently named one is active. Once active it stays active until the user switches or says otherwise. When you write into a ticket folder, name the ticket in your reply alongside the path.

With a ticket context active, route by kind:

- **Into the ticket folder:** `plans/`, `designs/`, `brainstorm/`, `reports/`, `bugs/`. These are about the ticket's work and should close with it.
- **Stay in the main workpad:** `journals/` (session-scoped — the narrative often outlives the ticket) and `goals/` (project-scoped — the ticket itself is the goal; don't duplicate it).
- **Judgment call:** `research/` and `specs/`. Ask: *would someone on a different ticket want this?* If yes, main workpad. If it only makes sense against this ticket's deliverable, ticket folder. When a ticket produces a spec that outlives it, promote it to the main workpad on close.

The ticket folder mirrors the workpad's kind subfolders, created on demand, same file naming including date prefixes. The ticket root holds only ticket-level files (`context.md`, etc.) — never loose plans or reports. The "when to create a subfolder" rules still apply within ticket folders (cascades of related files get their own dated subfolder).

For main-workpad files written under an active ticket context, put the ticket id in the slug (`2026-05-05-14-42-auth-token-leak.md`) so they stay findable from either side.

## File naming

Use a `YYYY-MM-DD-hh-` prefix on filenames in `reports/` and `plans/` at minimum. The hour helps when multiple artifacts land on the same day — which is common during active work — and keeps directory listings naturally sorted by recency. Apply the same prefix to `journals/`, `bugs/`, and `research/` entries; it's almost always the right call there too. For `goals/`, `designs/`, and `specs/`, the prefix is optional — these are referred to by name more than by date, so a descriptive slug alone is fine (e.g. `goals/q2-onboarding-flow.md`, `specs/event-schema.md`).

After the prefix, use a short kebab-case slug describing the topic: `2026-05-05-14-auth-token-leak.md`, not `2026-05-05-14-report.md`. The slug is what the user will skim for later.

## When to create a subfolder

Single artifact → single file. Don't wrap one report in a folder.

Create a dated subfolder when a piece of work will produce **multiple related files** — typically a research cascade, a multi-part report with appendices, or a plan with supporting design notes that belong together. The subfolder takes the date prefix and slug; files inside it can drop the date prefix since the parent already carries it.

Example:
```
reports/
  2026-05-05-14-auth-token-leak.md          ← single report
  2026-05-05-15-q2-perf-audit/              ← cascade
    overview.md
    db-findings.md
    frontend-findings.md
    recommendations.md
```

## Picking the right kind of document

The categories overlap. These are the distinctions that matter:

**Plan vs. spec.** A plan is a sequence of steps you intend to take. A spec encodes something that shouldn't change — an invariant, a contract, a frozen decision. Default to `plans/`. Promote to `specs/` only when the content is meant to be referenced repeatedly as a source of truth and is not expected to be revised as work progresses.

**Goal vs. plan.** A goal says *what we're trying to reach* — acceptance criteria, a milestone, a story-level outcome. A plan says *how we'll get there*. If you find yourself writing "and then I'll…", you're writing a plan, not a goal.

**Report vs. journal.** A report is a snapshot — it can be revised as new information arrives, and the latest version is the version that matters. A journal is append-only and tells the story of a problem, including missteps, dead ends, and course corrections. Post-mortems, multi-day bug hunts, and architectural-correction narratives are journals. If the historical sequence is itself part of the value, it's a journal. If only the current conclusion matters, it's a report.

**Brainstorm vs. design.** A brainstorm is divergent — multiple options, tradeoffs, no commitment. A design is convergent — one approach, fleshed out enough to build from.

## Lifecycles

Most work follows one of these flows. Use them as a guide for what to create next, not as a mandatory pipeline — skip stages when they wouldn't earn their keep.

**Feature work:** `brainstorm → goal → design → plan`. Start with options, settle on what success looks like, design the approach, then break it into steps.

**Investigative or reactive work:** `report → design → plan`, or `report → plan`, or just `plan`. You usually start by reporting on what's there or what's broken; a design is only needed if the fix is non-trivial.

When moving between stages, create a new file in the next folder rather than mutating the previous one. The earlier artifact stays as a record of how thinking evolved.

## What "write a report" means by default

When the user says "write a report on X" without further direction:

1. Create a markdown file in `<workpad>/reports/` with the `YYYY-MM-DD-hh-<slug>.md` naming.
2. Put the actual findings in the file.
3. In your reply to the user, **summarize directly** — don't restate the whole report. Mention the file path so they can open it.

The same default applies to "write a plan", "draft a brainstorm", etc. — the user wants a file in the right folder plus a short verbal summary, not the file's contents pasted back into chat.

## Steering other skills

If you're operating under another skill that wants to write a markdown artifact (a research note, a design sketch, a status report), and a workpad exists or is reasonable to create, route the artifact through the workpad rather than that skill's default location — including the ticket routing above when a ticket context is active. The other skill governs **what goes in the file**; this skill governs **where the file lives and what it's called**. They compose cleanly.

## What this skill deliberately does not cover

- The internal structure or formatting of reports, plans, designs, etc. That's up to the user, the project's conventions, or another skill.
- Git workflow for workpad files (whether to commit them, branch them, etc.).
- Ticket lifecycle (whether a closed ticket folder moves to `archive/`, how to promote artifacts out of a ticket, etc.).
- Tooling for searching or indexing the workpad.

If the user asks for help with any of those, treat it as a separate concern.