docs: move migration guidance out of always-loaded CLAUDE.md - #564
Merged
Conversation
The root CLAUDE.md loads into every session, so each line is resident context for the whole session. Three sections were paying that cost without needing to be always available. The Alembic procedure (autogenerate mechanics, the two app/analytics lineages, the continuous-aggregate backfill, resolving split heads) becomes a skill that loads on invocation. The domain-exception-to-HTTP mapping rules move to sparkth/api/CLAUDE.md, which loads only when working under that directory. Safety-critical prohibitions deliberately stay in the root file, where they are always loaded: "never edit an existing migration file" and "never use bare except Exception" are unchanged, as are the general exception rules that apply outside the API layer. Also drops the Red-Green-Refactor enumeration, which restates a generic practice the superpowers:test-driven-development skill already covers, and folds the duplicate GitHub Project Management section into the commit-conventions section that already pointed at the same skill. Root CLAUDE.md drops from 14821 to 11003 characters. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Drops the nested sparkth/api/CLAUDE.md introduced earlier on this branch and restores the full domain-exception-to-HTTP mapping rules to the root CLAUDE.md, unchanged from main. The nested-file approach loads the rules only when working under sparkth/api/, but domain exceptions are raised from services, engines, and plugins — code that lives outside that directory — so the rules need to be resident everywhere. The branch now makes a single relocation: the Alembic procedure moves into the database-migrations skill. Root CLAUDE.md lands at 12727 characters (from 14821 on main). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
abdulrafey1
changed the title
hamza-56
approved these changes
Aug 4, 2026
…e-md # Conflicts: # CLAUDE.md
main made the continuous-aggregate backfill automatic: `make migrations` now delegates to the `sparkth migrate` CLI command, which applies both lineages and then runs the backfill, with `make analytics-backfill` kept for refreshing a single aggregate by name. The skill was written against the earlier behavior, where the backfill was a separate one-off manual step after migrating, so its "Applying migrations" and continuous-aggregate sections described a workflow that no longer exists. 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
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
Trims the always-loaded root
CLAUDE.mdby moving the database-migration procedure into a skill that loads on demand, cutting resident context in every session from ~14.8k to ~12.7k characters.Changes
docs: move the Alembic procedure (autogenerate mechanics, the two app/analytics lineages, the continuous-aggregate backfill, resolving split heads) into a newdatabase-migrationsskill that loads on invocationdocs: drop the Red-Green-Refactor enumeration — it restates a generic practice already covered by thesuperpowers:test-driven-developmentskill; the TDD directives themselves are unchangeddocs: fold the duplicate## GitHub Project Managementsection into the commit-conventions section that already pointed at the same skilldocs: add the new skill to the Additional Documentation tableSafety-critical prohibitions stay in the root file, always loaded.
Never edit an existing migration file. No exceptions.andNever use bare except Exception blocks.are untouched. The whole Exception Handling section — including the domain-exception-to-HTTP mapping rules — stays in the root file unchanged: domain exceptions are raised from services, engines, and plugins outsidesparkth/api/, so those rules need to be resident everywhere.How to Test
/context;database-migrationsshould appear in the skill listing with its description.Notes
No migration, no breaking change, no env var, no dependency change. Documentation and agent-guidance files only — no runtime code is touched.
This is deliberately standalone and based directly on
main, so it can merge independently of the in-flight permission-groups / org-tree PR stack.This description was written with the assistance of an LLM (Claude).