reliquary/skills/workpad/SKILL.md

name, description

name

description

workpad

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 `superpowers/` 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 thinking-in-markdown so the user can always find what was written and when.

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 superpowers/ 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 Claude Code runs commands in subshells that may not inherit the user's interactive env, and the value may live in a project-local .env file rather than the actual environment. Try, in order:
   • uv run --quiet --with python-dotenv python -c "from dotenv import load_dotenv; import os; load_dotenv(); print(os.environ.get('WORKPAD_FOLDER',''))" if uv is available. This loads .env from the current working directory before reading the variable, which catches the common case where WORKPAD_FOLDER is set per-project in a .env.
   • 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, not values in .env files. If any of these prints a non-empty path, treat it as the workpad base.
3. Project-local ticket folder. Some projects keep a sibling folder outside the main repo for per-ticket scratch (e.g. ../<repo>-tickets/ or a path the user has mentioned before). If such a folder is configured for this project, prefer placing the workpad inside it (e.g. <ticket-folder>/workpad/). When in doubt whether one exists, ask.
4. /docs/workpad at the project root, if a /docs folder already exists.
5. 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

If one of these optional folders is needed and doesn't exist yet, create it. Don't create folders speculatively.

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. 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.).
• Tooling for searching or indexing the workpad.

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