Appearance
Source:
docs/research/README.md. Edit it there; this page is generated at build time.
Research
The reading a decision rested on. One file per question, named after the question rather than numbered — these are not a sequence and nothing refers to them by index.
The distinction from docs/adr/ is worth keeping sharp:
| Records | |
|---|---|
docs/adr/ | What we decided, and what we gave up by deciding it. Short. |
docs/research/ | What we read before deciding. Long, with sources, including the parts that argued the other way. |
An ADR that has to justify itself at length is usually an ADR with a research document missing behind it.
What belongs here
A document is worth writing when a decision turned on facts that were not obvious and are expensive to re-derive — vendor behaviour, framework source, a protocol's actual contract. Not when the decision was a preference.
Two conventions both current files follow, and the next one should:
- Check primary sources. Vendor documentation, a pinned source tag, the framework code already in
vendor/. Not write-ups about them. - Say when a source is silent. Where the evidence runs out, write that down instead of filling the gap with reasoning that reads like evidence.
Each file names the issue it was written for, so a reader who arrives from the issue and a reader who arrives from the directory both land somewhere useful.
What's here
| Document | Written for | What it settled |
|---|---|---|
migrations-on-deploy.md | #17 | Migrate before the symlink flip, dump outside the release tree, never migrate --isolated — and the rule that makes rollback honest, now enforced by scripts/check-migration-safety.php. |
deploy-tooling.md | #18 | Deployer 8.x with localhost() + local_archive, because ln -sfn is not atomic and Deployer's swap is. |
scheduler-view-packages.md | #25 | Take spatie/laravel-schedule-monitor for the run records and build the Filament page ourselves — no package ships the picked design, and the one Filament plugin over Spatie's data stops at Laravel 12. |