Set up the decisions convention in stash-docs #3

New issue

Open

opened 2026-08-07 13:33:04 -04:00 by agent · 0 comments

agent commented

2026-08-07 13:33:04 -04:00

Member

AGENTS.md in stash-ios carries this under the build standard:

Decisions get a short file in stash-docs. Record the reasoning, not just the outcome — the
thing worth keeping is why the alternative was rejected, because that is what a future reader
cannot reconstruct.

stash-docs today holds a LICENSE and an empty README.md. There is no decisions folder, no
naming scheme and no template, so the rule has nowhere to land and nothing has been recorded
against it.

Why this is being filed now

Working the reopened #9 in stash-ios produced exactly the kind of decision the rule is about:
transcript parts each keep their own WEBVTT signature and assembly strips the repeats, rather
than the alternative of dropping the signature from every part after the first. The rejected
alternative is the interesting half — it would have made raw concatenation work, at the cost of a
part being unreadable on its own mid-recording, which is the only reason parts exist at all.

Codex raised the missing file during the plan review. Wes's call was to skip it there rather than
invent a decisions convention inside a bug fix, and to file this instead. The reasoning lives in
AGENTS.md and in the VTT.swift doc comment meanwhile, so nothing is lost — it is just not
where the standard says it should be.

What this issue needs

A decision, not just a folder:

Where they live and what they are called. decisions/NNNN-short-slug.md is the common shape,
but a date-prefixed one reads better in a directory listing and does not need a counter.
What is in one. Context, the decision, the alternatives rejected and why. Short — the rule says
"a short file", and a template that invites an essay will produce nothing at all.
Whether existing decisions get backfilled or the convention only applies going forward. There
are several already sitting in AGENTS.md prose that would read better as their own files —
audio as one continuous file rather than chunks, filenames as a cross-client contract, no
Figma step, XcodeGen over a committed .xcodeproj.
Whether an index is maintained by hand or the directory listing is the index.

Done when

The convention is written down in stash-docs/README.md, the folder exists with at least one real
decision in it, and AGENTS.md points at it specifically rather than at the repository in general.

`AGENTS.md` in `stash-ios` carries this under the build standard: > **Decisions get a short file in `stash-docs`.** Record the reasoning, not just the outcome — the > thing worth keeping is why the alternative was rejected, because that is what a future reader > cannot reconstruct. `stash-docs` today holds a `LICENSE` and an empty `README.md`. There is no decisions folder, no naming scheme and no template, so the rule has nowhere to land and nothing has been recorded against it. ## Why this is being filed now Working the reopened #9 in `stash-ios` produced exactly the kind of decision the rule is about: transcript parts each keep their own `WEBVTT` signature and assembly strips the repeats, rather than the alternative of dropping the signature from every part after the first. The rejected alternative is the interesting half — it would have made raw concatenation work, at the cost of a part being unreadable on its own mid-recording, which is the only reason parts exist at all. Codex raised the missing file during the plan review. Wes's call was to skip it there rather than invent a decisions convention inside a bug fix, and to file this instead. The reasoning lives in `AGENTS.md` and in the `VTT.swift` doc comment meanwhile, so nothing is lost — it is just not where the standard says it should be. ## What this issue needs A decision, not just a folder: - Where they live and what they are called. `decisions/NNNN-short-slug.md` is the common shape, but a date-prefixed one reads better in a directory listing and does not need a counter. - What is in one. Context, the decision, the alternatives rejected and why. Short — the rule says "a short file", and a template that invites an essay will produce nothing at all. - Whether existing decisions get backfilled or the convention only applies going forward. There are several already sitting in `AGENTS.md` prose that would read better as their own files — audio as one continuous file rather than chunks, filenames as a cross-client contract, no Figma step, XcodeGen over a committed `.xcodeproj`. - Whether an index is maintained by hand or the directory listing is the index. ## Done when The convention is written down in `stash-docs/README.md`, the folder exists with at least one real decision in it, and `AGENTS.md` points at it specifically rather than at the repository in general.

agent added the

type/infrastructure

labels

2026-08-07 13:33:04 -04:00

agent referenced this issue from Stash/stash-ios

2026-08-07 13:44:36 -04:00

M1-09: VTT part writer — one-minute transcript chunks #9

agent referenced this issue from Stash/stash-ios

2026-08-07 14:18:13 -04:00

M1-09 follow-up: make the transcript parts actually assemble #24