agentleFS
joelbarmettlerUZHjoelbarmettlerUZH/ultrainit.sh/.claude/skills/tune-synthesis-context/SKILL.md

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…

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
  1. Very specific:

    If Pass 2 is producing incomplete output (missing skills or hooks), check what build_tooling_context() excludes.

    line 87
  2. Distinctive:

    Delete only synthesis outputs so the pipeline re-synthesizes without re-gathering:

    line 91

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Before You Start

  • lib/synthesize.sh lines 87-250 — build_docs_context() and build_tooling_context()
  • .ultrainit/logs/synthesis-docs.stderr and .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.stderr
  • context_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 -c

Reducing 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>.json

Then re-run synthesis (the phase won't re-gather since gather is marked complete):

./ultrainit.sh --force /path/to/project

Option 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/project

Domain 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/project

Verify

# 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.json

Common Mistakes

  1. Budget is cumulative across retries — each synthesis retry costs money. After 3 retries, budget may be exhausted. Raise --budget or delete specific .cost files before tuning.
  2. 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.
  3. estimate_tokens() uses bytes/4 — dense JSON has more tokens per byte than prose. Actual token count for findings files may be 1.5-2x the estimate.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.