Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

AI Task Router

Pick the smallest context set. Do not load all docs.

Mandatory first step: read token-policy.md.

Second step: classify the user task into one row below. Read only the Read first files, then use rg -n before opening any file listed under Then read only if needed.

User taskRead firstThen read only if needed
Build/check issuecommands.mdexact failing command output, then tools/xtask/src/build.rs range found by rg
Run/QEMU/debug issuecommands.md, repo-map.mdexact tools/xtask/src/qemu.rs range found by rg; logs only via tail -n 120 or focused rg
Package/stage/registry issuecontracts.mdaffected RUSTOS.package.toml, then exact package_manifest.rs or stage.rs range
Kernel API/changekernel-api-map.mdrelevant kernel/*/src/api.rs, then backing module range found by symbol search
Kernel boot-order changekernel-api-map.md, contracts.mdkernel/src/main.rs, then exact kernel/executive/src/boot.rs range
Logging changecontracts.mdconfig/rustos.toml; open tools/build_log_cfg.rs only after searching category/level name
Fault injection changecontracts.md, commands.mdconfig/rustos.toml; exact libs/rustos-fault-injection, tools/xtask/src/qemu.rs, or kernel/nucleus-core/src/util/fault_injection.rs range found by rg
Runtime launch/session issuecontracts.mdlibs/runtime-control/src/lib.rs, then exact services/runtimed/src/main.rs range
UI/rendering issuerepo-map.mdsearch services/uiserver/src; open only the matching render.rs or app/* range
Hardening requestcontracts.md, kernel-api-map.mdhighest-risk boundary first; exact API, broker, service, lock, memory, or device path found by rg
Ring0/ring3 ownership or microkernel boundarycontracts.md, ring3-evacuation.mdcommercial-microkernel-closure.md for final-shape/LOC questions; kernel-api-map.md, then exact broker, service, driver, input, storage, or compat path found by rg
Add service/app/driverworkflows.mdone closest existing manifest, one closest source file, target manifest/source only
Docs updatedocs/SUMMARY.mdtarget doc only; AI docs only if agent context changes

Stop rules:

  • If task can be answered from one AI doc and one source file, stop searching.
  • If rg returns an exact symbol/function, open only a narrow range around it.
  • If the user asks for implementation and the target owner is clear, stop reasoning and patch the smallest viable slice.
  • Reserve extended reasoning for debugging, failure analysis, structural review, security review, or explicit design-choice requests.
  • For hardening, rank the OS risk first; do not spend time hardening unrelated low-risk helpers after the high-risk boundary is identified.
  • If debugging hits a structural blocker or lacks runtime evidence, stop and report the blocker instead of making speculative patches.
  • Do not open a backing module until the relevant api.rs or manifest contract shows the needed boundary.
  • Do not inspect logs/ for build/check failures; use the failing command output first.
  • Do not inspect logs/ for run/debug failures until the QEMU command line and failing symptom are known.
  • Follow token-policy.md for generated paths, logs, and Cargo.lock.
  • If a human doc duplicates an AI contract, use the AI contract unless writing prose.
  • If source contradicts AI docs, source wins; update AI docs if task includes docs.
  • If a contract change is discovered, update the focused AI doc before finishing.

Context budget defaults:

  • Simple answer: this file plus one focused AI doc.
  • Small code change: one focused AI doc plus 1-3 source ranges.
  • Debugging: one command doc plus failing output or one focused log snippet.
  • Cross-subsystem work: add contracts.md and the relevant API map only when the boundary crosses crates or services.

Escalation rule:

  • Before opening a fourth source file or second large range, summarize the current hypothesis and name the exact missing fact.