Workplan

Work Plan Skill

Work plans are timestamped markdown files that survive auto-compaction. They are your external brain for multi-step work.

File Convention

• Location: Project root, gitignored
• Name: WORKPLAN-YYYYMMDD-slug.md (e.g., WORKPLAN-20260228-auth-refactor.md)
• One file per task/phase. Start fresh for each distinct effort. Do not recycle a finished plan for unrelated work.
• But do not start a second plan for work an existing one already covers. If a WORKPLAN-*.md for this effort is already in the project root, it is the live record, whoever wrote it and however stale it looks. Adopt it and keep writing in it. See Resume for how to treat what is already in it.

Roadmap Markers

Every roadmap item carries one of four markers. Two of them require a trailing note, because the person reading this file weeks from now has none of your context and cannot ask you.

• [ ] Open. Not started, or started and not finished. No note needed.

• [x] Done. Implemented and verified, with a matching entry in the Verification Log. Nothing else earns this marker.

• [!] Blocked. Cannot be attempted right now for a reason outside the work itself: a missing credential, an unreachable host, a file the client never sent, a decision you do not own. Different from failed. A failed step can be retried this minute; a blocked step cannot be started at all. Write it as:

  - [!] 4. Step description. BLOCKED since YYYY-MM-DD on <what is missing>. Owner: <who can unblock it>. Unblocks when: <the concrete event>.

• [-] Dropped. Requested, and deliberately not being done. Write it as:

  - [-] 5. Step description. DROPPED YYYY-MM-DD by <who decided>. Reason: <why>.

Marker discipline:

• Never delete an item from the Roadmap. Cuts become [-], blockers become [!]. An item that vanishes reads later as work nobody ever asked for, which is the one story the file must not tell.
• [!] and [-] are not failure and not a reason to stop. Mark the item, say so, move to the next one.
• A dropped item also gets a Decisions entry, because that is where a reader looks for why.

Actions

Create (/workplan or /workplan create)

1. Read first. Before writing the plan, read all relevant files, issues, context.

2. Ensure .gitignore includes WORKPLAN-*.md (add if missing).

3. Pick a scope mode before writing the plan:

   • EXPANSION: "What's the 10-star version?" Dream big, push scope up.
   • HOLD: "Make this bulletproof." Scope is right, maximize rigor.
   • REDUCTION: "What's the minimum that ships value?" Cut ruthlessly. Before cutting anything, write down the criterion you are cutting against ("not needed for the Friday demo", "not on the paid path") in the Context section, and cite it in every [-] you create. A cut with a stated criterion is defensible in a month. A cut without one looks like something got forgotten.

   Defaults: greenfield feature = EXPANSION, bug fix / launch prep = HOLD, time-constrained = REDUCTION.

   The mode is a reading of current conditions, not a commitment. Re-check it at every Update.

4. Create the file with this template:

# Work Plan: [Title]

Created: YYYY-MM-DD HH:MM
Last updated: YYYY-MM-DD HH:MM
Status: IN PROGRESS | DONE | CLOSED WITH OPEN ITEMS
Mode: HOLD / EXPANSION / REDUCTION
Cut criterion: [REDUCTION only. What a step has to fail to get cut.]

## Context

[Why this work exists. The problem. Root cause. Key constraints. Links to issues/PRs.]

## Roadmap

Markers: `[ ]` open, `[x]` done and verified, `[!]` blocked, `[-]` dropped.
`[!]` and `[-]` carry their note on the item itself.

- [ ] 1. Step description
- [ ] 2. Step description
- [ ] 3. Step description

## Decisions

[Log architectural or approach decisions with timestamps]
- [HH:MM] Chose X over Y because Z

## Discovered Issues

[Things found along the way that were not in the original scope]
- [HH:MM] Found ... while working on step 2

## Verification Log

[Each completed item gets a verification entry. Name the command or the exact
steps, and the result someone else would see running it again.]
- [HH:MM] Step 1: VERIFIED - ran `npm test`, 42 passed, 0 failed
- [HH:MM] Step 3: VERIFIED - logged in at localhost:3000 with an email account
  and a Google account, both landed on /dashboard; a wrong password returned 401

Update (/workplan update)

1. Read the active WORKPLAN-*.md file(s) in the project root.
2. Update "Last updated" timestamp.
3. Check off completed items with verification timestamps. Rule 1 applies to every tick.
4. Re-check every [!] item. Still blocked? If the blocker cleared, do the work. If not, refresh the note with today's date so the next reader knows the block is current and not a fossil.
5. Re-check the scope mode. The deadline moved, the budget changed, the bug turned out to be three bugs: any of those can change the mode. If it changes, edit the Mode: line and log the change in Decisions with the reason. If it does not change, leave it and move on.
6. Add any new discoveries or decisions.
7. Report current status to the user, naming every [!] and [-] item and what you need from them.

Close (/workplan close)

1. Read the active workplan.
2. Account for every roadmap item. Each one is [x] with a Verification Log entry, [!] with a current blocked note, or [-] with a reason. An item you cannot honestly put in one of those three is not ready, and the plan is not ready to close.
3. Never tick an item in order to close a plan. Closing is not a reason for anything to become done. If you feel that pull, that is the signal the plan closes with open items instead.
4. Run final verification (build, tests, manual checks).
5. Set the status. DONE if every item is [x]. CLOSED WITH OPEN ITEMS if any [!] or [-] remains. A plan holding a permanently blocked item is closeable, and it closes in that state.
6. Add final summary:

## Completed

Closed: YYYY-MM-DD HH:MM
12 of 14 items implemented and verified. Build passes. Tests pass.

Open at close:
- [!] 9. Rotate the staging API key. BLOCKED since 2026-03-04 on the vault
  credential. Owner: platform team. Unblocks when: read access is granted.
- [-] 13. Add SAML login. DROPPED 2026-03-02 by the user. Reason: out of scope
  for this launch, tracked in ISSUE-441.

7. Tell the user what closed open, in the same message where you report the close.

Resume (after compaction)

When context has been compacted or you're unsure where you left off:

1. Find active workplans: look for WORKPLAN-*.md in project root.
2. Read the workplan file.
3. Audit the checkmarks before you trust them. A [x] you did not write this session is a claim, not evidence, whether it came from a compacted session, a previous run, or another person. For each one, find its Verification Log entry.
   • Entry names what was run and the result: trust it.
   • No entry, or an entry nobody could disprove ("looks right", "should work", "manually tested"): the item is unverified. Set it back to [ ] and note in Discovered Issues that you reopened it and why.
   • If re-running the check is cheap, just run it. That settles the question faster than reasoning about it.
4. Re-check [!] items. A blocker may have cleared while you were away, and a stale blocked note is the most common reason real work sits untouched.
5. Continue from the first [ ] item.

Rules

1. VERIFIED means tested. Not "I think it works." Run it, see it pass, then mark verified. Write the entry so a stranger could re-run it and get the same answer: the command or the exact steps, and the result. "Manually tested, works" is not a verification. It names nothing, so it can never turn out to be false.
2. Update timestamps on every change. Future-you (post-compaction) depends on this.
3. New discoveries go in immediately. Do not keep them only in context.
4. Never delete the plan until the user confirms the work is done.
5. One concern per checklist item. Break big steps into smaller verifiable pieces.
6. If a step fails verification, log the failure, keep it [ ], add what went wrong. Failed is not blocked: a failed step can be attempted again right now, so it stays open.
7. If a step cannot be attempted at all, mark it [!] with the owner and the unblock condition. Never tick it, never quietly drop it, never leave it as a bare [ ] that the next reader will waste an hour retrying.
8. A deliberate refusal is recorded, not hidden. Anything requested that you are choosing not to do becomes [-] with a reason, and you say so to the user in the same turn. Silence about it reads as agreement.