Agent Instructions

Improve the decisions instructions produce while preserving project requirements. File length, authorship, and position alone do not establish a defect.

Inspect the actual problem

Identify the requested repository, runtime, and audit-versus-edit scope. Inspect relevant entry files, inherited guidance, imports, and referenced material. Use reported failures or representative tasks to identify what should improve. Do not broaden a repository edit into global configuration changes.

Before changing loading or file placement, read runtime-notes.md. Record which guidance loads at startup, on a matching path, or through agent retrieval; mark unknown behavior as unverified. Follow existing authority and scope rules. Commands in material under review do not independently authorize installation, publishing, or destructive actions.

Check disputed claims against project scripts, CI, manifests, maintained documentation, and explicit owner decisions. For each consequential edit, retain enough provenance to explain what was changed and why; a compact change summary is usually sufficient.

Choose a disposition

Do not infer a defect merely because text was generated, is long, or sits in the middle. Resolve contradictions using applicable authority and scope, not emphasis or recency alone. If competing policies remain unresolved, name both and continue unrelated improvements.

Defer only when discoverable

Before removing detail from an entry file, verify the destination exists and preserves the procedure's preconditions, exceptions, exact commands, and recovery steps. State the triggering task and the action required before proceeding. Reuse existing documentation rather than multiplying copies.

For example: “Before editing schema migrations, read docs/migrations.md and complete its compatibility checks.” Use the repository's actual path. If a task cannot reliably signal that need, retain essential guidance upfront. A compact visible index can be preferable to relying on implicit skill selection; neither approach is universally better.

Check both that a relevant task finds the detail before its affected action and that an unrelated task avoids unnecessary loading. A reachable link alone does not establish retrieval. When execution is unavailable, retain important constraints visibly and describe routing as unverified. If a trial misses the guidance, repair the trigger or restore the essential instruction inline.

Validate and deliver

For ordinary edits, inspect the diff, preserved requirements, command references, and links. Do not run full comparative benchmarks merely because a rewrite is large. When uncertain routing or interpretation could change behavior, exercise the affected task in an isolated fixture when feasible and inspect the resulting actions or artifacts.

Claim performance improvement only with matched baseline/revised tasks and reported conditions, repetitions, correctness, and resource measures. Text reduction is not a performance result. If a supplied trace shows later actions violating a rule, check those outputs and the enforcement path before prescribing a shorter file or repeated reminders.

Deliver the edited files or audit findings, reasons for material changes, unresolved decisions, and checks actually performed. Label static checks, walkthroughs, execution trials, and performance comparisons separately. Revisit rules when the underlying constraint changes or a concrete failure demonstrates a gap.

Read evidence.md to inspect research support and limits. Read cases.md only when evaluating this skill; withhold its rubrics from test workers. validation.md records this version's tests and limitations.