mit einem Klick
docs-engineering
// Audit and update all project documentation to stay in sync with the current development status of the 5thPlanet SEGA Saturn emulator.
// Audit and update all project documentation to stay in sync with the current development status of the 5thPlanet SEGA Saturn emulator.
Perform a project-wide code review of the 5thPlanet SEGA Saturn emulator, covering correctness, emulation accuracy, code quality, tests, documentation, and style.
Stage, commit, and (when a remote exists) push changes with a well-formed Conventional Commits message.
Manage the full software release process for the 5thPlanet workspace — version bumps, changelogs, Git tags, and (when applicable) GitHub releases.
Perform a project-wide security and safety audit of the 5thPlanet workspace.
| name | docs-engineering |
| description | Audit and update all project documentation to stay in sync with the current development status of the 5thPlanet SEGA Saturn emulator. |
When performing documentation engineering, always follow these steps:
Survey recent changes — run git log --oneline -20 and skim the diffs of recent feat(...) commits. This surfaces new opcodes, new chips, new peripherals, and behavioral changes that documentation may not yet reflect. Note which milestone tasks each commit advances; the roadmap should already reflect them but rolling back is cheap and worth verifying.
Audit all documentation against the current codebase. The review scope must include — without exception:
README.md — project pitch, accuracy-first design axis, build/test/run instructions, current milestone status, test count. (Create if absent.)CLAUDE.md — stack (Rust 2024, no_std + alloc for sh2, workspace unsafe_code = "forbid"), workspace layout, key gotchas (SH-2 PC base = instr_pc + 4, delay slots, big-endian, write-through cache, queue-and-drain pattern, destructure-self for disjoint borrows), test conventions. Must have a Saturn-side architecture section once crates/saturn/ is non-stub. (Create if absent.)doc/roadmap.md — milestone table; each task's status must reflect reality (✅ done / 🚧 in progress / pending). Each milestone's "what's landed so far" / "what landed" block should list the actual test breakdown by file family.doc/glossary.md — Saturn-architecture vocabulary (chip names, address ranges, register acronyms, hardware-specific concepts). New chips / acronyms / address ranges introduced in crates/saturn/ get entries; cross-link with [term] references to other glossary entries.doc/ chapter files as they are added (e.g. doc/sh2-isa-notes.md, doc/cycle-timing.md, doc/bus-protocol.md).lib.rs doc comments — must provide a real module overview, not a one-line summary. Both crates/sh2/src/lib.rs and crates/saturn/src/lib.rs (and any future crates/*/src/lib.rs) should give a cargo doc reader enough to navigate.Revise and update any documentation that is stale, incomplete, or inconsistent with the current code. In particular:
crates/saturn/ grow modules that aren't tracked) AND add it to the glossary AND add it to the relevant CLAUDE.md architecture section.scu_dsp arriving in M3), update README's "Workspace" section, CLAUDE.md's "Workspace layout" block, and write a real module-overview doc-comment in its lib.rs.README.md. Use cargo test --workspace 2>&1 | grep '^test result' | awk -F'[. ]' '{s+=$5} END {print s}' to compute it exactly.Cpu::mem_* / Cpu::step so they stay accurate.Remove completed items from any TODO list in doc/. If a brief summary of completed work is warranted, add it to the relevant README.md or roadmap section before deleting the TODO entry.
Commit documentation changes using the commit-and-push skill with scope doc, grouped by topic. Don't mix unrelated documentation changes in a single commit. A natural split is:
docs: commit just flips the roadmap row to ✅ done (no other doc work). This is the project's established cadence — keep doing it that way.doc/*.md chapter is its own commit (typically grouped with whatever feature commit motivated it, or as its own docs: commit when added retroactively).Skill invocations that try to bundle "feature lands + roadmap flip" into one commit are wrong — the project's git log is structured so each feat(...) is closely followed by a one-line docs: companion, and that one-line companion is greppable from docs: alone.