Choose the smallest reusable form that preserves the verified value. Use a note for understanding, a checklist for human judgment, a script for deterministic operations, a project convention for repository-wide behavior, a skill for agentic interpretation, and automation only when a stable trigger should run a known action.
Note: preserve understanding
Use a note when the main value is an explanation, decision, example, or source. A note can answer why a configuration exists or what an error taught you.
It should state context, evidence, limitations, and links. Do not turn an unverified AI explanation into documentation.
Checklist: preserve judgment
Use a checklist when steps recur but a person must inspect evidence or choose:
- [ ] Confirm the assignment's AI policy.
- [ ] Inspect the starting repository state.
- [ ] Review every changed file.
- [ ] Run relevant tests.
- [ ] Record unresolved risks.
A checklist supports judgment; it should not pretend a checked box proves the underlying result.
Script: preserve deterministic operations
Use a script when the same explicit inputs should produce defined outputs with clear failures. Good candidates include formatting, conversion, validation, and repeatable file generation.
A script needs input validation, safe defaults, useful errors, tests, and a preview or dry run when changes could be costly. The next post develops this choice.
Project convention: guide repository behavior
Use repository documentation or an instruction file when every contributor or tool needs the same setup, commands, naming, scope, or review expectations. Keep durable project facts there. Keep one-time requests in the task or prompt.
Project guidance must remain versioned with the project and agree with the README, tests, and actual commands.
Skill: preserve agentic judgment
Use a skill when an agent should apply a recurring multi-step method that requires interpretation, tool choice, and validation. A skill may contain instructions, references, scripts, and templates.
Do not use a skill to hide a deterministic operation that should be a tested script. Do not include secrets, private course content, or claims that the agent cannot verify. Product-specific skill behavior changes, so follow the current official documentation for the agent environment you use.
Automation: attach a stable trigger
Automation connects a defined trigger to a known workflow: run a test nightly, create a backup on schedule, or validate a repository on each proposed change.
Automate only after the manual process and failure behavior are understood. Require observable logs, bounded permissions, safe retries, and a way to stop.
Use the decision tree
Is the value mainly an explanation?
├─ Yes → Note
└─ No
Does a person need judgment each time?
├─ Yes → Checklist
└─ No
Are inputs, outputs, and failures deterministic?
├─ Yes → Script
└─ No
Is the guidance specific to one repository?
├─ Yes → Project convention
└─ No → Consider a skill
Does a stable event need to run the verified asset?
└─ Yes → Add automation after testing the underlying form
An artifact can evolve. A note may reveal a recurring checklist. Repetition may justify a script. A script can later be scheduled. Move up only when evidence supports the added maintenance.
Compare examples
| Repeated value | Best starting form | Reason |
|---|---|---|
| Why a path error occurred | Note | Explanation matters |
| Pre-submission review | Checklist | Human judgment remains |
| Format five files | Script | Operation is deterministic |
| Required project test command | Project convention | All contributors need it |
| Research and draft a post with source review | Skill | Interpretation and tools vary |
| Run validated checks on each pull request | Automation | Stable event and action |
Common mistakes
- Writing a script before understanding the steps.
- Using a checklist for work a test can enforce.
- Encoding one-time preferences as repository rules.
- Creating a skill that only wraps one command.
- Scheduling an unreliable workflow.
- Preserving AI output without evidence or policy boundaries.
Do this now
Choose one verified learning record and follow the decision tree. Create the smallest fitting artifact, state why the simpler form is insufficient, and identify what evidence would justify a more complex form.
Log what you learned
Record only:
- Result: What did the action produce?
- Evidence: What observation, test, or source supports that result?
- Next action or unresolved question: What should happen next?
Next, learn when deterministic work should become tested code rather than another AI prompt.