Why does the entry file keep getting harder to use?
A payment change adds migration instructions. A styling change adds another paragraph. Soon even a button edit loads deployment details, while the copied startup command is obsolete. More documentation has made the relevant information harder to find.
Copying configuration creates another place to maintain the same fact. This lesson turns that crowded file into an entry point that leads a task to the right material.
Keep information that earns its place
Keep broadly relevant conventions that are difficult to discover from the environment, plus essential pointers. Read commands, dependencies and directory facts from their actual configuration. Explain unusual constraints where needed without duplicating the configuration itself.
State when a task should open each document. Keep infrequent material beside its subject. The reader should be able to select a reference from the task, before opening every document.
Use it as an index of pointers to important files, and even then aggressively prune it for no-ops.
— Matt Pocock
Pruning needs evidence too
When instructions look vague, stale or repetitive, identify the behaviour they affect before removing or merging them. A familiar sentence may preserve a boundary established after a real failure. Test its effect rather than assuming it does nothing.
Keep platform requirements in force. Splitting documentation also has costs: people maintain more files and agents follow more pointers. Observe both lookup effort and maintenance effort when deciding how far to split.
Checklist structure adapted from Matt Pocock's skills repository, MIT: skills/. Example wording is ours.
Clear triggers
Each pointer identifies the task that needs it.
One factual source
Read configuration facts from configuration.
Visible costs
Consider both reading effort and maintenance effort.
Exercise: replace a pile of instructions
| Existing instruction | Our replacement | Verification |
|---|---|---|
| Be careful and read the docs | When changing refunds, read the state rules in docs/refunds.md | A refund task finds that document |
| Ten copied lines of commands and dependencies | Read package.json for commands and dependencies | The current script can be located |
| Always read every deployment detail | When changing the release process, read docs/release.md | A styling task need not load release material |
Give a reference a useful trigger
- Task: Replace “See docs/data.md” with a pointer useful for a migration task.
- Check: Would a copy edit also trigger it? Does the destination exist?
Suggested approach
When changing persisted fields or data migrations, read the compatibility and recovery rules in docs/data.md. This is an illustrative path; verify existence and freshness in an actual project.
Done means the navigation guides a real task
Every pointer has a trigger, an accessible destination and a purpose. Configuration facts have one maintained source, and necessary constraints remain discoverable. A reader can explain why this task needs a document, beyond observing that the entry file is shorter.
Move executable constraints into the process described in standards and checks.
Quick reference
Root file
Broadly relevant, hard-to-discover information and essential pointers.
References
Keep them near their subject and connect them with task conditions.
Pruning
Observe behaviour while preserving effective constraints and mandatory requirements.
Sources and attribution
- Matt Pocock, pointers and pruning, 2026-07-04.
- Public AGENTS.md guide, independently interpreted.
- Minimal instruction files, independently interpreted.
- skills repository: checklist adaptation identified above; Copyright (c) 2026 Matt Pocock.
- Site copyright details. The complete MIT licence follows at the end of this page.
skills MIT notice
The structure adapted here comes from mattpocock/skills, MIT licence, Copyright (c) 2026 Matt Pocock. The complete licence follows, identical to the repository LICENSE.
Full licence: mattpocock/skills
MIT License
Copyright (c) 2026 Matt Pocock
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
Unofficial, non-commercial study notes, with no affiliation with or endorsement by Matt Pocock. Quoted works belong to their authors; MIT reuse carries separate copyright and licence notices.