Skip to content

Separate current Skills docs from history - #36

Merged
raghubetina merged 1 commit into
mainfrom
codex/docs-skills-usability
Aug 14, 2026
Merged

Separate current Skills docs from history#36
raghubetina merged 1 commit into
mainfrom
codex/docs-skills-usability

Conversation

@raghubetina

Copy link
Copy Markdown
Contributor

Summary

  • replace the root README with a concise status and task router
  • replace the release wall with a current approval-gated five-stage runbook
  • move completed chronology and old shell transcripts into explicitly non-authoritative archives
  • add maintainer, evidence, and 62-case eval indexes with retrieval guards
  • preserve the exact authenticated-journey invocation, retry, and cleanup authorization boundaries

Verification

  • sh script/check: 69/69 tests
  • exact CLI package check at d37d8b67...: PASS
  • candidate digest unchanged: e89a14b7a28ec5b6384038cec106f31c7496f076344726b02b3a674b344755f5
  • installable Skill/reference/schema and release/compatibility.json: unchanged
  • independent documentation review: PASS
  • git diff --check: PASS

No package, tag, catalog, npm, service, or deployment mutation.

Root entry and release pages mixed present instructions with completed
rollouts, evidence, and evaluator notes. Replace them with concise routes
and a current approval-gated runbook.

Index evidence and evals, preserve historical detail in an explicitly
non-authoritative archive, and keep installable Skill bytes unchanged.
@raghubetina
raghubetina merged commit a86618a into main Aug 14, 2026
2 checks passed
@raghubetina

Copy link
Copy Markdown
Contributor Author

Post-merge review, hosted CI green (69/69 plus the exact package check; candidate digest unchanged, so this is
provably a docs-only change to the packaged surface). The structural move is sound: the root README becomes a
status-and-router page, the release wall becomes a five-stage runbook, and chronology moves to archives that
say outright they are non-authoritative. The retrieval guards in the new indexes (tests asserting routes
resolve) are what make a router trustworthy; an unchecked router rots into a pile of dead links.

One strength worth naming: the approval, retry, and cleanup authorization boundaries were preserved verbatim
rather than summarized during the move. Reorganizations are where load-bearing sentences get paraphrased into
weaker ones, and the diff shows these were transplanted, not rewritten.

Succession note: the five-stage runbook this PR introduced was subsequently amended by #40 and #41 (two-turn
smoke, sequence approvals). The structure holds; read the approval specifics through those later PRs.

@raghubetina

Copy link
Copy Markdown
Contributor Author

Documentation has two natural tenses and most repos mix them until neither works. Current-state docs answer
"what is true now, and what do I do next." History answers "what happened, in what order, with what evidence."
This PR splits them cleanly, and the split has a rule worth memorizing: a reader should never have to know the
project's past to act correctly in its present.

The mechanics: the README becomes a short router (status table plus links by task), the release process
becomes a runbook you execute top to bottom, and everything chronological (completed migrations, old shell
transcripts, superseded decisions) moves under an archive whose header says it is non-authoritative. That
label matters more than the move. An old transcript sitting in the main docs is a trap: it looks like
instructions, and an agent or a new hire will follow it. The same transcript in a folder marked "historical,
not authority" is evidence, safely quarantined.

Notice also that the indexes come with tests. A router page is a data structure, and this repo treats it like
one: automated checks assert the routes resolve. Without that, reorganizations decay at the speed of the next
rename.

The habit to steal for any project: when you finish a piece of work, ask which sentences you wrote are
"current state" and which are "what happened," and file them in different places. Your future self wants the
first kind fast and the second kind only when auditing.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant