Split production runbook into docs/runbooks/, reorganize scripts/, add operate-prod skill - #352
Merged
Merged
Conversation
… in glossary Grill session output: spec for splitting RUNBOOK_production.md into docs/runbooks/, scripts/ family reorg, and the /operate-prod skill. CONTEXT.md gains an Actors section pinning Operator = the human with decision authority. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…ipts/ by family, add operate-prod skill
Implements docs/_handoffs/runbook-split-operate-prod-spec.md (grilled 2026-06-10;
Linear issue deferred on workspace cap):
- RUNBOOK_production.md split verbatim into docs/runbooks/{update-loop,bootstrap,
invocations,monitoring,services,troubleshooting,feedback-loop}.md + README map;
RUNBOOK_command_center.md relocated to command-center.md with §6 folded in;
service-stop precondition added to update-loop.md + services.md.
- scripts/ regrouped into services/ linear/ verify/ ops/; verification companion
RUNBOOKs ride with their scripts into verify/; spike_alp288 deleted; ps1
installers' $ProjectRoot computation updated for the extra directory level.
- .claude/skills/operate-prod/SKILL.md: thin router over the runbooks with
standing directives, autonomy gate, never-autonomously list, self-correction duty.
- Dead-pointer guard extended to docs/runbooks/** + the skill; exclusion now
judged on REPO_ROOT-relative parts so the guard no longer no-ops in worktrees.
- All live references updated (src command_center messages, test loaders,
skills, CLAUDE.md nav); docs/design left point-in-time.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- Repair perl double-replacement (src/alphamind/scripts/verify/ corruption) and
revert the point-in-time 2026-05-24 deferral audit to its historical text.
- ps1 installers: correct the stale one-level-up comment (root is two levels up
now), qualify bare RUNBOOK references with their new homes.
- Stale operator pointers: config/{assets,command-center,security}.yaml comments,
e2e companion's CSS sidecar path, alphamind.scripts docstrings + the
MissingArtifactError message template, comb-collector-logs' pre-existing
_common.py path (refactored to _common/retry.py).
- Runbooks: drop orphaned EOF separators from the split, cite § 5.7 / § 8.9
subsections precisely, README documents the retained monolith numbering,
services.md cites the service-stop precondition instead of restating it.
- operate-prod skill: add the command-center route the sweep found missing; trim
directives that restated CLAUDE.md (local-time) or runbook content (.env form).
- Guard: dedupe the scan set, document why only the router-class skill is
scanned (12 false positives vs 1 catch across other skills), and add
test_runbook_section_refs_resolve validating every cross-doc '<doc>.md § N'
prose reference against the target's actual headings.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- verify_command_center.py: repo-root anchor parents[1] -> parents[2] (the move
to scripts/verify/ shifted the script one level deeper; the CLI-only
_prepare_run_setup path read scripts/config/*.yaml and failed at runtime,
invisible to the suite which injects repo_config_dir).
- ps1 installer location comments now actually updated (<repo>\scripts\services\,
two levels up) — the prior perl pattern silently failed on backslash escaping.
- Fixture READMEs' forward-looking RUNBOOK_{analyst,proposal_pre_processor,
strategist}.md refs re-pathed to scripts/verify/ for consistency with their
re-pathed verify_*.py siblings.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
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
1 participant
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.
Summary
scripts/RUNBOOK_production.mdinto nine task-focused runbooks underdocs/runbooks/(README map + update-loop, bootstrap, invocations, monitoring, services, troubleshooting, feedback-loop, command-center), preserving the monolith's § numbering so cross-doc references stay stable; the command-center runbook relocates with old §6 folded in, and the update loop gains a service-stop precondition (market open AND open positions → Operator confirmation).scripts/intoservices/,linear/,verify/(verification artifacts + their companion RUNBOOK docs), andops/family subdirectories; delete the unreferenced ALP-288 spike; fix the ps1 installers'$ProjectRootfor the new depth..claude/skills/operate-prod/SKILL.md— a thin router from operator situations onto the canonical runbooks, carrying the agent-side autonomy gate, never-autonomously list, and self-correction duty (gotchas accumulate introubleshooting.mdvia docs-only PRs).test_runbook_section_refs_resolve, validating every cross-doc<doc>.md § Nprose reference against the target's real headings.Implements
docs/_handoffs/runbook-split-operate-prod-spec.md(operator-grilled 2026-06-10). Linear issue deferred — workspace is over the free-tier cap; ALP-842 rollup recommended first.Test plan
.github/workflows/ci.yml) green on the PR — lint on Linux + full pytest on Windowsruff check,ruff format --check,mypy,lint-imports)tests/docs/(incl. new § validator),tests/scripts/(273),tests/command_center/— 1,088 totalscripts/RUNBOOK_*references outside point-in-time docs (docs/design/, archives)🤖 Generated with Claude Code