How to Synthesize and Maintain Doctrine
Who is this for (1)
- Stakeholder Persona: External Tech Lead Evaluator — Written for the External Tech Lead Evaluator reader.
This guide covers the day-to-day synthesis workflow: checking status, linting, running synthesis, validating the bundle, and recovering from stale or corrupted state.
For background on the synthesis model, see How Charter Works.
1. Check doctrine status
Before running synthesis, check what the current state is:
uv run spec-kitty charter statusThe output reports:
- Whether the bundle is current or stale relative to
charter.md - The synthesis/operator state
- With
--provenance: per-artifact provenance details
# Include provenance detailsuv run spec-kitty charter status --provenanceIf status reports the bundle as stale, it means charter.md has been edited since the last
synthesis. Run lint and synthesis to bring it current.
2. Lint your charter file
Before synthesizing, check for graph-native decay:
uv run spec-kitty charter lintLint detects:
- Orphans: artifacts referenced in the DRG but without a backing definition
- Contradictions: two directives with conflicting instructions for the same action
- Staleness: artifacts whose provenance references a deleted or superseded built-in directive
Filter by severity to focus on critical issues:
uv run spec-kitty charter lint --severity highScope to a specific mission:
uv run spec-kitty charter lint --mission my-feature-slugFix any issues reported by lint before proceeding to synthesis.
3. Synthesize doctrine (dry-run first)
Always preview the synthesis before applying:
uv run spec-kitty charter synthesize --dry-runThe --dry-run flag stages and validates artifacts but does not promote them to the live tree.
Review the output to confirm the synthesis plan is correct.
charter synthesize reads the charter interview answers, resolves synthesis targets from the DRG
and doctrine, and writes artifacts to .kittify/charter-packs/. On a fresh project where
.kittify/charter/generated/ is missing or empty, it materializes the minimal artifact set: a
.kittify/charter-packs/ directory and a PROVENANCE.md record.
4. Apply synthesis
When the dry-run output looks correct, apply:
uv run spec-kitty charter synthesizeOn success, the artifacts are promoted to .kittify/charter-packs/. The runtime can now use the
updated doctrine for governed mission context injection.
Additional options:
# Use fixture adapter for offline testinguv run spec-kitty charter synthesize --adapter fixture
# Skip code-reading evidence collection (faster, less thorough)uv run spec-kitty charter synthesize --skip-code-evidence
# Skip best-practice corpus loadinguv run spec-kitty charter synthesize --skip-corpus
# Print evidence summary and exit without running synthesisuv run spec-kitty charter synthesize --dry-run-evidence5. Partial resynthesis with resynthesize
When only a specific directive or tactic has changed, use charter resynthesize to regenerate
just the affected artifacts without touching unrelated ones:
# Regenerate a specific tacticuv run spec-kitty charter resynthesize --topic tactic:how-we-apply-directive-003
# Regenerate all artifacts referencing a built-in directiveuv run spec-kitty charter resynthesize --topic directive:DIRECTIVE_003
# Regenerate all artifacts from a specific interview sectionuv run spec-kitty charter resynthesize --topic testing-philosophy
# List valid topic selectorsuv run spec-kitty charter resynthesize --list-topicscharter resynthesize uses a structured selector to identify the target set. Unrelated artifacts
are never modified.
6. Validate the bundle
After synthesis, validate the bundle schema:
uv run spec-kitty charter bundle validateThis validates the bundle against the CharterBundleManifest v1.0.0 schema. A clean validate confirms the bundle is ready for runtime use. Check after every synthesis run.
7. Check provenance
To verify what synthesized the current doctrine artifacts:
uv run spec-kitty charter status --provenanceThe --provenance flag includes per-artifact provenance details in the output, showing which
synthesis run created each artifact and from what source.
8. Understanding staging state
When charter status reports a staging state or pending synthesis, it means synthesis artifacts
have been staged (validated) but not yet promoted to the live tree. To promote:
# Run synthesize without --dry-run to complete the promotionuv run spec-kitty charter synthesizeIf synthesis was interrupted, re-run from the beginning. Synthesis is designed to be re-runnable without side effects.
9. Recovery: stale or corrupted bundle
Symptoms of a stale bundle:
charter statusreports drift betweencharter.mdand the bundlespec-kitty nextinjects outdated context into agent promptscharter bundle validatefails with schema errors
Fix:
- Check current state:
uv run spec-kitty charter status - Lint for decay:
uv run spec-kitty charter lint - Regenerate the bundle if you have made manual edits:
uv run spec-kitty charter generate - Re-run synthesis:
uv run spec-kitty charter synthesize - Re-validate:
uv run spec-kitty charter bundle validate - Confirm:
uv run spec-kitty charter status
If charter status still shows drift after these steps, check .kittify/charter/generated/ for
any malformed agent-generated YAML that may be blocking promotion. The adapter reads those files
before synthesis.