nix-self-iteration-protocol

Purpose

• Continuously improve the entire instruction system by diagnosing specific failure modes, reducing ambiguity, and placing rules at the correct level.
• Keep global AGENTS streamlined and migrate reusable specialized workflows to skills.

Applicable Scenarios

• Evaluate or rewrite AGENTS.md
• Split one large prompt into multiple skills
• Rewrite skill description to improve triggering precision
• Determine whether a rule should be placed in global, skill, repo-local AGENTS, tooling, or MCP
• Design regression tests or eval prompts for prompt / skill
• Diagnose recurring prompt failure or usage friction

Inapplicable Scenarios

• Ordinary coding or debugging tasks
• Ordinary knowledge creation tasks
• Ordinary domain decision support, rather than instruction system design

Diagnostic Process

1. First determine whether this is really a prompt / routing / instruction design problem; if it is more likely insufficient context supply, a tooling / MCP gap, missing repo-local constraints, a model capability boundary, or a lack of eval, fix it there first, and do not default to changing the prompt.
2. Clarify the observed symptom, recurring failure, or friction.
3. Before proposing changes, first classify the failure.
4. Determine which level the fix should land at.
5. Propose only the minimal but effective change.
6. Explain the expected benefits, possible regressions, and affected tasks.
7. Specify how to verify the change with a minimal eval package or stable task set.

Failure Type Classification

• mode-selection failure
• scope-control failure
• evidence / verification failure
• quality-bar failure
• format / delivery failure
• knowledge-traceability failure
• decision-calibration failure
• over-constraint or under-constraint
• routing-description failure
• instruction redundancy / contradiction

Rule Placement Level

global AGENTS

Keep only rules that are "always in effect, cross-task, and low-ambiguity".

skill

Carry reusable specialized workflows, domain protocols, richer templates, negative examples, and task-specific quality thresholds.

repo or directory-level AGENTS

Place repository-specific commands, conventions, build/test commands, and local routing hints.

tooling / checks

If a rule is better constrained deterministically by tests, linters, formatters, scripts, or evals, do not rely on the prompt alone.

MCP / External Systems

If what is truly missing is external system access capability rather than behavioral guidance, prioritize tool / MCP integration.

Change Record Template

For each change, output at least in the following order, and do not skip fields:

• observed symptom
• evidence
• likely root cause
• failure class
• placement layer
• minimal change
• eval plan
• rollback signal

skill description Rules

• Use single-line text for description.
• In description, write only "trigger scenarios", and do not write Do not use when, Outputs, Success, unless eval clearly proves that supplementation is necessary.
• Prioritize Chinese, while also adding common English trigger words, to facilitate triggering by mixed Chinese-English requests.
• description is routing logic, not marketing copy.
• Put the real boundaries, counterexamples, output requirements, and completion criteria in the body.
• If a skill falsely triggers or misses triggering, change the description first, then consider expanding the body.

Change Strategy

• Rules should be few and strong.
• Merge or delete overlapping instructions.
• Replace abstract slogans with observable behavior.
• When writing to a DSL, Preset, Reference, field schema, or other shared object, first confirm that the object boundary, target users, and evaluation function are stable; if they are not yet stable, keep an evidence layer or candidate layer first.
• Do not add new rules unless they can change behavior on real tasks.
• Runtime prompts should stay sufficiently lean to avoid bloating into a full charter again.

Regression verification discipline

Do not judge whether a prompt has been improved by intuition alone. For every change, prepare at least a minimal eval package:

• 2 should-trigger cases
• 2 near-miss should-not-trigger cases
• 1 baseline comparison (pre-change description / prompt / old rules / no skill)
• 1 held-out case

If a change affects cross-task routing, global AGENTS, or the boundaries of multiple skills, a stable task set should still be maintained over the long term, covering:

• one coding bugfix task
• one local refactor boundary case
• one knowledge organization / synthesis task
• one decision-support task
• one simple conversation task
• for each skill whose routing was changed, at least one should-trigger and one should-not-trigger case

Output requirements

• When asked to modify a prompt or skill, output the specific rewritten text, not just criticism.
• When evaluating, separate "diagnosis" from "suggested changes."
• When splitting, provide both: the split-out skills and the remaining global prompt.

Completion criteria

• Obvious non-prompt / routing issues have been ruled out first.
• The change is grounded in a clear failure mode or persistent friction.
• The placement layer choice is clear and defensible.
• The description sufficiently supports stable routing.
• The verification method, baseline, and rollback signal have been made explicit.

Anti-patterns

• Continuing to bloat the global prompt in order to solve a specialized problem
• Adding rules to "look more complete"
• The actual problem is in the description, yet the body text is piled up instead
• Continuing to pile on concepts, hierarchies, or schema terms on top of existing findings without changing routing, the output contract, or the verification method
• Keeping mutually contradictory or duplicate rules
• Accepting prompt changes without doing real regression checks