filstawski/playbook

docs-migration-status-tracking

Track an incremental migration or a guideline-compliance backlog as an explicit checklist/status table in the docs, checked off as each piece actually completes, rather than trusting memory or a stale "done" claim.

View source

How to use

  1. Copy the installation command and review the source package before installing it in your own agent environment.
  2. Check the source document for required tools, credentials and supported hosts.
  3. Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/filstawski/playbook --skill docs-migration-status-tracking

Before you start

  • Installation does not include a model subscription, API allowance or permission to access your files.
  • Repository stars and installation counts describe activity, not an independent quality or security test.
Original skill document

Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.

Rule

When old and new coexist during a migration — or when a written convention exists ahead of full codebase compliance — keep a literal status table in the docs, and update it the moment each row actually changes state, not in a later cleanup pass.

Migration port-status table:

markdown
| Manager | v2 file | Notes |
| ------- | ------- | ----- |
| Image   | ✅ `images.ts` | Shareable · has userDelta · S3 + CDN owned |
| Folder  | ✅ `folders.ts` | Shareable · has userDelta · S3 preview owned |
| Domain  | ✅ `domains.ts` | Non-shareable · custom deleteFlow |
| Invite  | ⏳ pending | |

Guideline-compliance backlog, same shape, applied to "written convention vs. actual code" instead of "old system vs. new system":

markdown
## Decided (keep docs in sync when you refactor code)

- [x] Section order on structures — enforced for all files, any size.
- [x] Named exports for managers — no `export default`.

## Structures — layout / surface

- [ ] Reorder all structures to match the guideline's section order.
- [ ] Add numbered section comments to every structure file (currently
      only `user.ts` has them).

Rules of thumb:

  • **A row's status reflects reality at time of reading, not at time of

writing.** The whole value of this doc is that someone can trust it without re-auditing the code — a status table that's gone stale is worse than no table, since it now actively misleads instead of just being silent.

  • Split "decided and enforced" from "still open" as separate sections

(checked-off vs. unchecked), the same way a roadmap note separates Resolved from Still-open (see docs-roadmap-notes) — a flat list that mixes settled and pending items forces a re-read of every row to know which is which.

  • When a rename or convention change ships, update the doc in the same*

change**, not as a follow-up. The most common way this pattern fails in practice: code renames an internal method (_patch → $patch, deprecating the old name) but the written guideline describing that method still shows the old name — now every reader of the guideline learns the wrong convention until someone notices the drift separately. If the doc update would be a second PR "later," that's the failure mode, not an acceptable sequencing.

  • This doc is disposable once the migration finishes — a fully-checked

table or a table with no ⏳/[ ] rows left has done its job; delete it or fold anything still relevant into permanent documentation rather than leaving a completed checklist around indefinitely. A doc that was true once shouldn't linger past being true.

Why

An incremental migration without a status doc means "is X migrated yet" requires reading the code every time someone needs to know — and worse, different people form different beliefs about migration status from whatever code they last happened to read, with no way to reconcile them. A guideline-compliance backlog exists for the same reason applied to "written rule vs. actual code": writing a convention down doesn't make the whole codebase follow it instantly, and without an explicit backlog, "already documented" quietly gets treated as "already true" by anyone who reads the guideline without also checking the code.

Exceptions

  • For a migration small enough to finish in one sitting (a handful of call

sites, done in one PR), a status table is unnecessary ceremony — this pattern earns its keep specifically when old and new coexist for a meaningful stretch of time.

  • Don't let the tracking doc become a place to defer decisions

indefinitely — an item that's sat unchecked for a long time with no progress is a signal to either prioritize it or explicitly decide not to do it (and remove the row), not to leave it as permanent background guilt.

See also

from this repository

More skills

All skills
filstawski
Community

api-manager-effects-and-populators

The two composition layers underneath the declarative manager pattern — deferred side-effects (realtime socket emit, audit log, CDN purge, all run independently via Promise.allSettled) and populators (batched, composable read-time enrichment, including the data-driven polymorphic feature table for share/like/comment/view-style cross-cutting features). Use when adding a new realtime event, wiring audit logging for a model, adding a derived/aggregate field to a manager's populated shape, or adding

1h installs
1
GitHub stars
0
Updated
Nov 3
filstawski
Community

code-polish

Pre-commit cleanup pass over the current change set: strip the debris left behind by trial-and-error iteration (debug logs, commented-out attempts, stacked workarounds, dead branches, defensive checks for impossible states, swallowed errors, any/ignore escapes), replace symptom patches with the one clean root-cause fix, then bring what remains up to professional standard — clear naming, doc comments on public API, idiomatic error handling, the project's own conventions, passing format/lint/typec

1h installs
1
GitHub stars
0
Updated
Nov 3
filstawski
Community

git-commit-messages

Conventional-commit-style message format — a type prefix (feat/fix/docs/ chore/refactor/...), an imperative present-tense summary under ~70 characters, an optional body explaining why rather than what, and no AI/assistant attribution or co-author watermark lines. Use when writing or reviewing a git commit message, or whenever an agent is about to run git commit and needs to know the message format and what not to include. Companion to git-commit-requires-approval (whether a commit should happen

1h installs
1
GitHub stars
0
Updated
Nov 3