feat: zeeker runbook — generate an operational RUNBOOK.md for data projects - #11
Merged
Conversation
New CLI command that generates the operational document humans and AI monitoring agents read to run, monitor, and interpret builds: - zeeker/commands/runbook.py — modular command following the existing commands/ style; requires a zeeker project (clean error + exit 1 outside one); writes RUNBOOK.md (--output PATH; refuses to overwrite without --force). - Auto-generated facts: project/database names and rich metadata from zeeker.toml, per-resource table (description, fragments, fragments_on_skip, FTS fields) plus detail bullets (facets, sort, size, ...), the standard build/deploy command reference, and the 0.9.0 status contract baked in verbatim: exit codes 0/1/2, the non-TTY line grammar ([OK]/[FAIL]/[SKIP], WARN[resource]:/WARN[build]:, SUMMARY footer with extra_counts), Skip kinds (up_to_date/blocked/disabled) with monitor guidance, __zeeker_report__ enrichment counters, and the full --json / --progress-file payload field list. - Six TODO placeholder sections marked "<!-- TODO: fill in -->" for per-project content (run narrative, env vars, cadence & yield, failure modes & recovery, backlog SQL, escalation). - Regeneration policy documented in the file header: --force overwrites the ENTIRE file, nothing is preserved. - Tests: packages/zeeker/tests/test_runbook.py (14 CliRunner tests) covering generation, overwrite protection, outside-project error, and the status-contract grammar strings. - CLAUDE.md command list updated. No version bump (rides 0.9.0). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Cuh5eJDfVowgpp22s7siE1
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
New
zeeker runbookcommand (--output PATH,--force) that generatesRUNBOOK.md— the operational document humans and AI monitoring agents read to run, monitor, and interpret builds of a data project.The generated file has two kinds of content:
Auto-generated facts from
zeeker.tomland this zeeker version:fragments_on_skip, FTS fields, facets, sort, etc.)build,--sync-from-s3,--setup-fts,--json,--progress-file,--fail-on-blocked,deploy)[OK]/[FAIL]/[SKIP],[SKIP] name <reason> (kind),WARN[resource]:/WARN[build]:, the SUMMARY footer with counters), the skip-kind table with_zeeker_updatesfreshness semantics and monitor guidance,__zeeker_report__counter semantics, and the full--json/--progress-filepayload field tablesSix TODO placeholder sections (
<!-- TODO: fill in -->+ hint blockquotes) for per-project content: run narrative, environment variables, cadence & expected yield, failure modes & recovery, backlog/progress SQL, escalation.Refuses to overwrite without
--force(which replaces the entire file — documented, with a--output RUNBOOK.new.md+ manual-merge recipe for refreshing facts). Version-stamped header makes template drift visible.Tests
14 new CliRunner tests (generation, flag rendering, overwrite policy, outside-project error, exact status-contract grammar strings). Full suite: 461 passed, 5 pre-existing skips.
Note
The status-contract text is a maintained copy inside
runbook.py, not runtime introspection — if the line grammar changes in a future version, update the template in step (the header version stamp exposes drift).The five Bucket-4 adoption PRs each contain a
RUNBOOK.mdgenerated by this command and hand-filled.🤖 Generated with Claude Code
https://claude.ai/code/session_01Cuh5eJDfVowgpp22s7siE1
Generated by Claude Code