SKILL.md

name

description

scientific-method

Explore and refine engineering ideas using an iterative scientific method: reason from first principles, analyze relevant code and context, propose candidate ideas, implement coherent change sets, and validate each iteration with the checks required for the task (runtime behavior, tests, and/or types). Use primarily for simplification, refactoring, API design, and debugging, and more generally for uncertain changes where one-shot reasoning is likely to miss better solutions.

Scientific Method

Overview

Use an evidence-driven loop instead of attempting one-shot solutions. Keep iterating through testable attempts until the best solution is found within constraints.

Primary Use Cases

• Simplify code without breaking behavior.
• Refactor structure while preserving runtime and type correctness.
• Explore and shape API design decisions through small experiments.
• Debug ambiguous failures by proving or disproving concrete hypotheses.

Loop Contract

Follow this loop every time:

1. Analyze relevant code and context.
2. State one candidate idea to try.
3. Implement the coherent change set needed to realize the idea.
4. Validate with the checks required for this task (runtime behavior, tests, and/or types).
5. Compare outcomes and decide whether to refine, replace, or branch the idea.

Do not skip required validation for the task. Do not batch multiple unrelated ideas into one iteration. Allow broad coordinated changes when they are required by the idea. Do not avoid radical changes when evidence supports them and acceptance criteria remain satisfied. Do not stop at the first working solution when better options are still plausible.

Iteration Protocol

Repeat until the best known solution is reached within constraints:

1. Analyze

• Read relevant code paths, data flow, and current behavior.
• Re-derive constraints from first principles before committing to a direction.
• Generate at least one alternative approach that does not mirror the current structure.

2. Hypothesize

• Write a short hypothesis as a concrete candidate idea.
• Keep it specific enough to implement and evaluate in one iteration.

3. Implement

• Apply the coherent change set needed to evaluate the hypothesis.
• If partial edits would leave the system invalid, update dependent parts together in the same iteration.
• Change boldly when needed, including large refactors, but keep scope anchored to acceptance criteria and invariants.
• Permit radical redesigns when they better satisfy first-principles constraints and do not violate required behavior.

4. Validate

• Run the checks needed for this task (runtime checks, automated tests, type checks, benchmarks, or other relevant verification).
• Use targeted checks first, then expand validation scope as confidence grows.
• If validation fails, inspect failure details before changing code again.

5. Evaluate

• If validation passes but better solutions are still plausible, run another iteration with a materially different idea.
• Stop when acceptance criteria are met and further iterations are unlikely to produce a meaningfully better outcome.
• Otherwise refine, replace, or branch the idea and start the next iteration.

Persistence Rules

1. Try multiple materially different approaches when initial attempts fail.
2. Keep exploring after first success when solution quality can still improve.
3. Avoid repeating the same approach with cosmetic variations.
4. Continue iterating until the best known solution is reached for current constraints.

Escalation Rules

Escalate deliberately instead of thrashing:

1. After 2 weak iterations, re-check assumptions, invariants, and problem framing from first principles.
2. After 3 failed iterations, widen investigation surface (adjacent modules, integration boundaries, environment differences).
3. If still blocked, present the user with concise options based on collected evidence.

Minimal Iteration Log

Track each cycle in compact form:

• Iteration number
• Hypothesis
• Change made
• Validation run(s)
• Validation result
• Decision (accept, refine, discard)

Completion Criteria

Finish only when all are true:

1. Acceptance criteria are met.
2. Required validations for the task pass at appropriate scope.
3. The selected approach is the best known option among explored alternatives.
4. Final explanation maps the selected approach to evidence and tradeoffs.