docs(plans): prefix with YYYY-MM-DD for chronological sort#368
Conversation
Renames every plans/*.md to plans/YYYY-MM-DD-<slug>.md so the directory self-sorts chronologically and stale plans become visually obvious. Dates come from each file's first-add commit. Also updates the three live inbound references (README.md, tko.io history.md, three within-plans cross-references) and adds a Naming bullet to the Plans section of AGENTS.md documenting the convention for future plans. Adversarial pass: general-purpose subagent (initiated; see follow-up if it surfaces findings). Scope: the rename + reference updates are markdown-only and cannot affect biome/tsc/build/vitest; biome explicitly ignores .md.
Adversarial review on the prior rename commit (7831b01) caught two related issues, both rooted in using committer date (%cs) instead of author date (%as) when deriving the date prefix: 1. plans/knip.md was written 2026-04-15 but landed the next UTC morning, so committer date read 2026-04-16. Renames to 2026-04-15-knip.md so it sorts with the other 2026-04-15 plans. 2. AGENTS.md Naming bullet said "when the plan was written," which matched intent but diverged from the implementation (committer date). Rewrites to name author date explicitly and to spell out the exact git command, so future agents reproduce the same answer. No other plans were off — the 12 others had identical author and committer dates. Adversarial pass: general-purpose subagent. Flagged 2 (knip date + AGENTS.md wording drift). Resolved: this commit. Finding 3 (split rename+edit commits defensively) rejected — current git rename- detection tied the three affected renames at the default threshold and history is preserved via git log --follow.
|
Warning Rate limit exceeded
Your organization is not enrolled in usage-based pricing. Contact your admin to enable usage-based pricing to continue reviews beyond the rate limit, or try again in 5 minutes and 39 seconds. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. 📝 WalkthroughWalkthroughThe pull request introduces and implements a date-based naming convention for plan files throughout the repository. Documentation in AGENTS.md is updated to specify how to derive dates from git author dates, and all existing plan file references across multiple files are updated to conform to the new dated naming format. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~8 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Pull request overview
Renames the repository’s plans/*.md documents to a YYYY-MM-DD-<slug>.md scheme so the directory self-sorts chronologically, and updates inbound links + contributor guidance to match.
Changes:
- Renamed plan docs under
plans/toplans/YYYY-MM-DD-<slug>.md. - Updated references to the renamed plan files (README + docs history + intra-plans links).
- Documented the new
plans/naming convention inAGENTS.md.
Reviewed changes
Copilot reviewed 6 out of 16 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
AGENTS.md |
Documents the new plans/YYYY-MM-DD-<slug>.md naming convention and how to derive the date. |
README.md |
Updates the “dark factory” plan link to the new dated filename. |
tko.io/src/content/docs/history.md |
Updates the GitHub link to the renamed dark-factory plan. |
plans/2026-04-22-browser-test-runner.md |
Adds/renames the browser test runner plan under the dated naming scheme. |
plans/2026-04-16-legacy-docs.md |
Adds/renames the legacy docs plan under the dated naming scheme. |
plans/2026-04-16-dark-factory.md |
Adds/renames the dark factory plan under the dated naming scheme. |
plans/2026-04-15-replace-make-lerna.md |
Updates intra-plan references to renamed plan filenames. |
plans/2026-04-15-knip.md |
Adds/renames the knip plan under the dated naming scheme. |
plans/2026-04-15-biome.md |
Updates references to renamed plan filenames. |
plans/2026-04-14-modern-tooling.md |
Adds/renames the modern tooling plan under the dated naming scheme. |
plans/2026-04-06-trusted-publishing.md |
Adds/renames the trusted publishing plan under the dated naming scheme. |
plans/2026-03-29-tsx-doc-examples-rollout.md |
Adds/renames the TSX docs rollout plan under the dated naming scheme. |
plans/2026-03-29-testing-modernization.md |
Updates the internal reference to the renamed testing modernization plan file. |
plans/2026-03-29-jsx-playground.md |
Adds/renames the JSX playground plan under the dated naming scheme. |
plans/2026-03-29-build-and-release-certainty.md |
Adds/renames the build/release certainty plan under the dated naming scheme. |
plans/2026-03-29-agent-verified-behaviors.md |
Adds/renames the agent verified behaviors plan under the dated naming scheme. |
Comments suppressed due to low confidence (1)
plans/2026-04-15-replace-make-lerna.md:101
- After the rename, step 1 now reads as copying this plan to the same file path it already has. If this step is meant to describe creating the plan file from some other location (issue/notes), consider rephrasing (e.g., “Create the plan at …”) or dropping the step to avoid a self-referential instruction.
| --diff-filter=A --follow --format=%as -- plans/<slug>.md | tail -1`. Use | ||
| author date, not committer date: a plan written late one day and landed |
There was a problem hiding this comment.
The example git command uses plans/<slug>.md, but the naming convention directly above is plans/YYYY-MM-DD-<slug>.md. As written, a future contributor following the convention won't have a plans/<slug>.md path to run the command against; consider updating the command to reference the actual filename pattern (or clarify when/how to run it) so the guidance is self-consistent.
| --diff-filter=A --follow --format=%as -- plans/<slug>.md | tail -1`. Use | |
| author date, not committer date: a plan written late one day and landed | |
| --diff-filter=A --follow --format=%as -- plans/YYYY-MM-DD-<slug>.md | tail -1`. | |
| Use author date, not committer date: a plan written late one day and landed |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 6b75c0a61a
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| **Naming:** `plans/YYYY-MM-DD-<slug>.md`, where the date is the **author | ||
| date** of the first commit that adds the plan — i.e. `git log | ||
| --diff-filter=A --follow --format=%as -- plans/<slug>.md | tail -1`. Use |
There was a problem hiding this comment.
The new Naming guidance says plans must be named plans/YYYY-MM-DD-<slug>.md, but the example command still queries plans/<slug>.md. In a repo that has already migrated to date-prefixed filenames, contributors following this instruction will get no date output for existing plans and can’t reliably reproduce the convention, which undermines the chronological sorting this commit is trying to enforce.
Useful? React with 👍 / 👎.
Copilot + Codex both flagged on PR #368 that the example git command queried plans/<slug>.md, but the convention one line up is plans/YYYY-MM-DD-<slug>.md. After the rename, no file matches the old pattern, so a contributor running the command to reproduce the convention gets nothing. Updates the command to use the actual filename pattern. Adversarial pass: PR reviewers (copilot-pull-request-reviewer, chatgpt-codex-connector, coderabbit) flagged this finding. Resolved by this commit.
Summary
plans/*.mdtoplans/YYYY-MM-DD-<slug>.mdsols plans/self-sorts chronologically and stale plans are visually obvious. Dates come from each file's author date on its first-add commit (git log --diff-filter=A --follow --format=%as).README.md,tko.io/src/content/docs/history.md, and three within-plans/cross-references.Naming:bullet to the## Planssection ofAGENTS.mddocumenting the convention, including the exact git command so future agents reproduce the same date.Why
plans/was a flat, unsorted pile — you had to open each file to know when it was written, and stale plans looked identical to live ones. Chronological prefixing turns the directory into a timeline. Author date (not committer date) is the right source: a plan drafted late one day and landed the next UTC morning should still sort by when it was written, which caughtknip.mdduring adversarial review.Test plan
git diff --stat --find-renamesshows 13 clean renames (git rename-detection ≥50% similarity held on the three combined rename+edit files)git log --follow plans/2026-04-16-dark-factory.md(and spot-checks on others) surfaces pre-rename historygrep -rnacross*.md,*.ts,*.astro,*.mjs,*.js,*.json,*.ymlfor each old slug — zero stale references6b75c0aOut of scope
No code, tests, or CI affected. Biome explicitly ignores markdown;
bun run verifyhas no touch-surface for this change.https://claude.ai/code/session_01Vk56tJZxSiLQPj26xhiPBV
Generated by Claude Code
Summary by CodeRabbit