name: post-task-workflow
description: After completing any feature, bug fix, UI improvement, or other meaningful change in this project, follow this workflow before reporting the task done.

Post-Task Workflow

Run this after the user confirms a task is complete (or after you finish work the user clearly approved). Do not run it for read-only work (research, questions, exploration) or for partial/in-progress steps.

1. Update the changelog (when user-facing)

If this change is something a user would notice and care about — a new feature, a visible improvement, or a fixed bug they'd have hit — add an entry to lib/changelog.ts before committing, so it ships in the same deploy and the "What's New" badge lights up for users.

• Prepend a new ChangelogEntry to the top of the CHANGELOG array (newest first).
• id: today's date YYYY-MM-DD (add a -b / -c suffix for a 2nd/3rd entry the same day). date: the same YYYY-MM-DD.
• tag: 'new' (a new capability), 'improved' (an existing thing got better), or 'fixed' (a bug a user would have hit).
• title + items: plain, user-facing language — what they get, not how it's built. No internal jargon, file names, or skill ids. Optional emoji for a little flourish.

Skip for changes users can't see: internal refactors, infra, tests, docs, data/pre-generation/backfill work, admin-only tooling.

This is distinct from §4 (LESSONS.md): changelog = user-facing highlights users read; LESSONS.md = internal notes for future-Claude. A task may warrant one, both, or neither.

2. Commit with a good description

Work happens on a task branch in its own worktree, never on main (a hook
blocks edits/commits on main). If you're still on main, run
scripts/worktree-new.sh <slug> first. See CLAUDE.md.

• Stage only the files relevant to this task (avoid git add -A / git add .).
• Write a commit message with:
  • Subject (≤72 chars): imperative mood, names the change.
  • Body: 1–3 short paragraphs covering what changed and why. Reference the user-facing behavior or bug if applicable. Skip the obvious "what" if the diff already speaks for itself — spend the words on why.
• Use a HEREDOC so formatting survives:

  git commit -m "$(cat <<'EOF'
  Short imperative subject
  
  Why this change exists and what it enables / fixes.
  Any non-obvious tradeoff or follow-up worth flagging.
  
  Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
  EOF
  )"

3. Push and open an auto-merging PR

Push the task branch and open a PR that auto-merges once CI is green:

scripts/worktree-pr.sh "Optional PR title"

This runs git push -u, gh pr create, and gh pr merge --auto --squash --delete-branch. CI (tsc --noEmit + next build) gates the merge; GitHub
squash-merges and deletes the branch automatically once it passes. Never push or
force-push directly to main — branch protection blocks it.

4. Append to LESSONS.md

Open LESSONS.md and add an entry at the top of the log:

## YYYY-MM-DD — <short title>

**Task:** one-line description of what was done.
**Lesson:** what future-Claude should remember next time it touches this area — a gotcha, a convention learned the hard way, a non-obvious dependency, a pattern that worked. Skip if there is genuinely nothing new to record (don't manufacture lessons).
**Files:** key files touched.

Only add a lesson if there's something non-obvious worth carrying forward. A routine bug fix with no surprises does not need a lesson — just note the task line and skip the lesson field, or omit the entry entirely. Quality over volume.

5. Deploy to Vercel (from main, after merge)

Deploy only after the PR has merged into main, and only from the main
checkout — never from a feature worktree (that ships an unfinished tree).

DB migrations run automatically on deploy (wired 2026-07-05): vercel.json
sets buildCommand: "node scripts/migrate.mjs run && npm run build", so every
production build applies pending ledger migrations first and fails loudly if one
fails. npm run db:status shows what's pending; npm run db:migrate remains the
manual escape hatch. See docs/migrations.md.

# in the main checkout, after the PR merged:
git checkout main && git pull
vercel --prod

• If Vercel is git-connected to main, the merge already triggers a production
  deploy — skip the manual command and just report the deployment.
• Report the deployment URL back to the user.
• If the deploy fails, surface the error — do not retry blindly or bypass
  build errors. Fix the root cause on a new task branch (repeat from step 1),
  then redeploy.

When NOT to run this workflow

• The user asked a question or requested research only.
• Work is partial / waiting on user input.
• Changes are scratch/experimental and the user has not asked to ship them.
• The user explicitly said "don't commit" or "don't deploy."

When in doubt, ask: "Want me to commit, log the lesson, and deploy?"