docs(skill): recommend cost-tier model per phase (#314)#391
Open
tirth8205 wants to merge 1 commit into
Open
Conversation
High-fan-out phases like `file-analyzer` dispatch dozens-to-hundreds of subagents per `/understand` run. When the session model is Opus, every analyzer inherits it and drains premium budgets even though the analyzer's work is largely deterministic (runs `extract-structure.mjs` plus templated summaries). Synthesis-heavy single-dispatch phases (`architecture-analyzer`, `tour-builder`) are where the strongest model actually pays off. The cleanest fix would be a per-agent `model:` frontmatter field, but that path is blocked: `model: inherit` is a Claude Code-only keyword that broke opencode with `ProviderModelNotFoundError` (issue Egonex-AI#167, PR Egonex-AI#200). Agent frontmatter must therefore stay portable, so this PR is documentation-only: - Add a "Model Cost-Tier Recommendations" section to `understand/SKILL.md` with a per-phase table and the explicit rationale for not using agent frontmatter. - Inline "Cost tier:" reminders at every phase dispatch step (`project-scanner`, `file-analyzer`, `assemble-reviewer`, `architecture-analyzer`, `tour-builder`, `graph-reviewer --review`). - Same hint added to `understand-knowledge/SKILL.md` Phase 3 for the high-fan-out `article-analyzer` path. - Document the shape of a future `config.json` `models` map (not wired into the runtime yet) so downstream tooling can converge. - README "Multi-Agent Pipeline" gains a "Model cost tiers" subsection with the same table and cross-link to SKILL.md. No agent frontmatter is modified — the opencode-portability constraint from CLAUDE.md is preserved. Closes Egonex-AI#314 Co-Authored-By: Claude Opus 4.7 (1M context) <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
Closes #314.
/understandPhase 2 fans out onefile-analyzersubagent per batch — dozens-to-hundreds per run. When the session model is Opus, every analyzer inherits it and drains premium budgets even though the analyzer's work is largely deterministic (it runs the bundledextract-structure.mjs+ emits templated summaries on top of tree-sitter facts). The strongest model only materially helps on the rare synthesis-heavy single-dispatch phases (architecture-analyzer,tour-builder).Why this is a docs change, not an agent-frontmatter change
The cleanest fix would be a per-agent
model:frontmatter field, but that path is blocked by an existing portability constraint documented in CLAUDE.md:So this PR is documentation-first. Orchestrators that support per-dispatch model selection are expected to apply the table; platforms that cannot route per-agent fall back to the session model with no behaviour change.
Per-phase recommendations introduced
project-scannerfile-analyzer(high fan-out)assemble-reviewerarchitecture-analyzertour-buildergraph-reviewer(only with--review)Files changed
understand-anything-plugin/skills/understand/SKILL.md— new "Model Cost-Tier Recommendations" section with rationale, table, and a future-shape sketch for aconfig.jsonmodelsmap (not wired into the runtime). Inline "Cost tier:" reminders at every phase dispatch step.understand-anything-plugin/skills/understand-knowledge/SKILL.md— Phase 3 (article-analyzer) gains the same hint; this is the other high-fan-out phase in the plugin.README.md— "Multi-Agent Pipeline" section gains a "Model cost tiers (per phase)" subsection with the table and cross-link to SKILL.md, plus the opencode-portability rationale.What this PR does not do
agents/*.mdfiles are untouched.config.jsonmodelsmap shape is documented as a future opt-in only.Test plan
grep -n "^model:" understand-anything-plugin/agents/*.mdreturns no matches (the opencode portability constraint is preserved).README.md,understand/SKILL.md,understand-knowledge/SKILL.md.