tune-synthesis-context
Skill8 starsChanged 7 months agoApache-2.0View on GitHub
estimate_tokens() in lib/synthesize.sh uses bytes/4 heuristic. Check actual file sizes: Module analyses for unimportant directories inflate the context significantly. Remove individual low-value findings: Then re-run synthesis (the phase won't re-gather since gather is marked complete): In lib/synthesize.sh, find build_docs_context() (lines 87-152). The function uses jq to extract specific fields. To reduce module analysis size, add field exclusions: Domain research and MCP discovery findings can add significant tokens with low marginal value. If Pass 2 is producing incomplete output (missing skills…
In this repository22 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- .github/workflows/CLAUDE.mdCLAUDE.md
- lib/CLAUDE.mdCLAUDE.md
- prompts/CLAUDE.mdCLAUDE.md
- schemas/CLAUDE.mdCLAUDE.md
- scripts/CLAUDE.mdCLAUDE.md
- tests/CLAUDE.mdCLAUDE.md
- add-bats-testSkill
- add-edge-testSkill
- add-gather-agentSkill
- add-integration-testSkill
- add-synthesis-fixtureSkill
- audit-prompt-schema-syncSkill
- bundle-and-verifySkill
- check-ci-locallySkill
- debug-agent-failureSkill
- fixture-syncSkill
- pre-pr-checklistSkill
- rebuild-test-imageSkill
- release-ultrainitSkill
- run-testsSkill
- validate-generated-artifactSkill
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 87
If Pass 2 is producing incomplete output (missing skills or hooks), check what build_tooling_context() excludes.
- Distinctive: line 91
Delete only synthesis outputs so the pipeline re-synthesizes without re-gathering:
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Before You Start
lib/synthesize.shlines 87-250 —build_docs_context()andbuild_tooling_context().ultrainit/logs/synthesis-docs.stderrand.ultrainit/logs/synthesis-tooling.stderr— raw errors.ultrainit/findings/— all findings files that get included in context
Diagnosis
1. Check the synthesis log for the error type
tail -50 .ultrainit/logs/synthesis-docs.stderr
tail -50 .ultrainit/logs/synthesis-tooling.stderrcontext_length_exceeded→ context is too large, reduce it- Missing artifacts in output → context may be too small (missing findings) or model confused by too much noise
2. Estimate context size
estimate_tokens() in lib/synthesize.sh uses bytes/4 heuristic. Check actual file sizes:
# Largest findings files (Pass 1 context)
du -sh .ultrainit/findings/*.json | sort -rh | head -10
# Module analyses are often the largest
du -sh .ultrainit/findings/module-*.json | sort -rh
# Check total bytes of what goes into Pass 1 context
cat .ultrainit/findings/*.json | wc -cReducing Context
Option A: Remove low-priority module analyses
Module analyses for unimportant directories inflate the context significantly. Remove individual low-value findings:
# List all module findings
ls .ultrainit/findings/module-*.json
# Remove one
rm .ultrainit/findings/module-<unimportant-dir>.jsonThen re-run synthesis (the phase won't re-gather since gather is marked complete):
./ultrainit.sh --force /path/to/projectOption B: Edit build_docs_context() to exclude fields
In lib/synthesize.sh, find build_docs_context() (lines 87-152). The function uses jq to extract specific fields. To reduce module analysis size, add field exclusions:
# Current: includes full module output
jq '. ' "$module_file"
# Reduced: exclude large arrays
jq 'del(.key_files, .domain_terms, .skill_opportunities)' "$module_file"Option C: Use --skip-research to exclude Phase 3 findings
./ultrainit.sh --skip-research /path/to/projectDomain research and MCP discovery findings can add significant tokens with low marginal value.
Expanding Context (for missing artifacts)
If Pass 2 is producing incomplete output (missing skills or hooks), check what build_tooling_context() excludes. Pass 2 intentionally omits key_files details, domain_terms, and skill_opportunities from module analyses to reduce tokens. If these are needed, edit lib/synthesize.sh lines 159-250 to include them.
Re-running Synthesis Only
Delete only synthesis outputs so the pipeline re-synthesizes without re-gathering:
rm .ultrainit/synthesis/output-docs.json
rm .ultrainit/synthesis/output-tooling.json
rm .ultrainit/synthesis/output.json
# Remove synthesis phase completion marker
jq 'del(.synthesize)' .ultrainit/state.json > /tmp/state.json && mv /tmp/state.json .ultrainit/state.json
# Rerun
./ultrainit.sh /path/to/projectVerify
# Verify synthesis completed
jq '.synthesize' .ultrainit/state.json
# Check output has expected artifact types
jq 'keys' .ultrainit/synthesis/output.json
jq '.skills | length' .ultrainit/synthesis/output.json
jq '.hooks | length' .ultrainit/synthesis/output.jsonCommon Mistakes
- Budget is cumulative across retries — each synthesis retry costs money. After 3 retries, budget may be exhausted. Raise
--budgetor delete specific.costfiles before tuning. - Deleting output files is not enough — you must also remove the phase completion marker from
state.json, otherwise the pipeline skips synthesis even after deleting the output files. estimate_tokens()usesbytes/4— dense JSON has more tokens per byte than prose. Actual token count for findings files may be 1.5-2x the estimate.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

