78 lines
4.1 KiB
XML
78 lines
4.1 KiB
XML
<decision_guidance>
|
|
<principles>
|
|
<principle>Prefer the smallest change that satisfies the request.</principle>
|
|
<principle>Prefer a single source of truth; avoid duplicating the same rule across multiple skills or files.</principle>
|
|
<principle>Ask a clarifying question only when location/scope or a potentially breaking change is ambiguous.</principle>
|
|
</principles>
|
|
|
|
<progressive_disclosure_guardrails>
|
|
<overview>
|
|
Progressive disclosure is a tool to reduce token load and improve navigation.
|
|
It is not a default requirement.
|
|
|
|
Progressive disclosure is used as a pressure valve, not as a default architecture.
|
|
</overview>
|
|
|
|
<default_policy>
|
|
<rule>Default to keeping essential workflow instructions in SKILL.md.</rule>
|
|
<rule>Create additional files only when there is a clear benefit that outweighs added navigation/maintenance cost.</rule>
|
|
</default_policy>
|
|
|
|
<good_reasons_to_split>
|
|
<rule>SKILL.md is becoming hard to skim (e.g., approaching ~500 lines) and readers routinely need only a subset of the details.</rule>
|
|
<rule>The skill has distinct sub-domains (e.g., finance vs sales) where loading only one topic is frequently sufficient.</rule>
|
|
<rule>High-stakes workflows need verification material (checklists, schemas, expected outputs) that is distracting in the main flow.</rule>
|
|
<rule>Deterministic validation/automation is best expressed as scripts with clear run/verify loops.</rule>
|
|
</good_reasons_to_split>
|
|
|
|
<bad_reasons_to_split>
|
|
<rule>Splitting purely for aesthetics or "nice folder structure" without a clear navigation or token benefit.</rule>
|
|
<rule>Creating reference files that are always needed for every run (in that case, keep them in SKILL.md).</rule>
|
|
<rule>Creating multi-hop chains (SKILL.md → reference.md → details.md) that require chasing links.</rule>
|
|
</bad_reasons_to_split>
|
|
|
|
<decision_test>
|
|
<rule>If the skill cannot be executed successfully without reading a linked file in most cases, move that content back into SKILL.md.</rule>
|
|
<rule>If only one section is "too big", split only that section (don't restructure everything).</rule>
|
|
</decision_test>
|
|
</progressive_disclosure_guardrails>
|
|
|
|
<scope_selection>
|
|
<default>
|
|
<rule>Default to project skills under <workspace>/.roo/skills* unless the user explicitly requests global skills.</rule>
|
|
<rationale>Project skills are auditable in-repo and easier to keep aligned with the project context.</rationale>
|
|
</default>
|
|
|
|
<global_trigger>
|
|
<rule>Use global skills only when the user explicitly wants portability across projects.</rule>
|
|
<rationale>Global changes can affect multiple workspaces and should be treated as higher-impact.</rationale>
|
|
</global_trigger>
|
|
|
|
<mode_specific_trigger>
|
|
<rule>Create mode-specific skills only when the skill is intentionally scoped to a single mode.</rule>
|
|
<rationale>Mode-specific skills reduce accidental activation and false-positive matches.</rationale>
|
|
</mode_specific_trigger>
|
|
</scope_selection>
|
|
|
|
<breaking_change_rules>
|
|
<rename_policy>
|
|
<rule>Treat renaming a skill directory (and therefore the skill name) as a breaking change.</rule>
|
|
<rule>Do not rename without explicit user confirmation.</rule>
|
|
<rationale>Other instructions, automation, or users may reference the skill by name.</rationale>
|
|
</rename_policy>
|
|
|
|
<name_mismatch_resolution>
|
|
<rule>Resolve directory/frontmatter mismatches before making additional edits.</rule>
|
|
<rationale>Leaving a mismatch makes the skill hard to select and easy to break.</rationale>
|
|
</name_mismatch_resolution>
|
|
</breaking_change_rules>
|
|
|
|
<resource_creation_rules>
|
|
<rule>Create scripts/, references/, or assets/ only when they materially improve execution and the user explicitly agrees.</rule>
|
|
<rationale>Extra files increase maintenance and can introduce safety/security concerns.</rationale>
|
|
</resource_creation_rules>
|
|
|
|
<handoffs>
|
|
<rule>If the user asks for edits outside <workspace>/.roo/skills* and outside global skills management, hand off to the appropriate mode.</rule>
|
|
</handoffs>
|
|
</decision_guidance> |