Repository navigation
Adopt Folder-Style Issue Specifications #2159
Description
Parent EPIC: #2003
Goal: Make folder-style specifications the only layout for new issues and EPICs while retaining existing single-file specifications as historical artifacts unless a later issue has an independent reason to migrate one.
Scope:
- Create a root ADR that records the prospective folder-only policy and no-bulk-migration decision.
- Align issue creation, Markdown, and issue-lifecycle guidance.
- Remove single-file paths as a new-spec option while retaining accurate legacy references.
- Keep issue-local artifacts beside ISSUE.md or EPIC.md.
Boundary: Do not bulk-migrate legacy specs, build migration tooling, or change refactor-plan conventions without a separate decision.
Verification: Run linter all and cargo test --doc --workspace; exercise a new-folder and legacy-spec scenario.
Activity
Merge #2161: docs(issues): add AI agent process specifications
da2ce7 commentedon Sep 10, 2026
One friction in the issue-specification conventions, found while aligning EPIC #2190 (PR #2193) with the guides; reported here because this issue owns the folder-style spec conventions.
F5 —
drafts/README.mdand the skill set a bar for "established parent" that nothing operationalizesdocs/issues/drafts/README.md:20-25: "Do not infer a parent EPIC from related work; leaveepic: nulland use an unnumbered name until the relationship is established."create-issue/SKILL.md:68-70: "Do not infer a parent EPIC from related issues, ADRs, or topic overlap. If the parent is not explicitly established, use an unnumbered descriptive draft folder."Symptom: neither document says what establishes the relationship. A maintainer assigning the child? A row in the parent's table? An argument from the parent's written scope? EPIC #2190 hands two drafts to EPIC #2003 on an argument from #2003's own stated In Scope and its stated exception — much stronger than topic overlap, and still not "explicit" by any stated test. The drafts were therefore prefixed
2003-and setepic: 2003before #2003's maintainer had seen them, which the rule appears to forbid and which no reviewer can adjudicate.Proposed resolution: name the establishing act. A workable test: the relationship is established when the parent EPIC's specification carries a row for the child, or a maintainer says so on the issue. Under that test EPIC #2190's two adoptions are established the moment #2003's table gains their rows — which is a concrete, checkable event, and the one PR #2193 now performs.
da2ce7 commentedon Sep 10, 2026
Two more frictions with folder-style specifications, found while drafting an unfiled specification with the
create-issueskill.F9 — An unfiled draft cannot satisfy the
branch:key of the ISSUE templateSources.
docs/templates/ISSUE.md:9fixesbranch: "{issue-number}-{short-description}". Thecreate-issueskill (Step 6, spec-only pull request) requires the key to name the-specbranch when the specification is submitted before implementation. A draft underdocs/issues/drafts/has no issue number yet, so it can satisfy neither form; the drafting flow the skill prescribes (draft, review, file, then move) produces a frontmatter value that is wrong until the last step. This is the ISSUE-template counterpart of F2 above, which reported the same key for the EPIC template.Proposed resolution. State the draft convention in the template itself (keep the
{issue-number}placeholder verbatim until filing, and note that a spec-only PR sets the-specname), so a draft with the placeholder is correct by definition and the move step replaces it.F10 — The line-wrapping rule for repository Markdown is not actionable
Sources.
.github/skills/dev/planning/write-markdown-docs/SKILL.md:93says, for.mdfiles in the repository: "Follow repo config (MD013 disabled, but keep lines readable)". Every recent folder-style specification (for exampledocs/issues/open/2175-merge-tool-symlink-exceptions/ISSUE.md) is written one line per paragraph, which the same table prescribes explicitly for GitHub issue and PR bodies.Symptom. "Keep lines readable" gives a contributor no rule to follow and a reviewer no rule to check, and it reads as permission to hard-wrap, which the examples do not do and which makes diffs of reflowed paragraphs unreadable.
Proposed resolution. State the rule for repository
.mdthe way the GitHub-surface row already does: one line per paragraph and per list item, no hard wrapping; the viewer wraps.da2ce7 commentedon Sep 10, 2026
Three more frictions in the same format, found while filing a folder-style specification (#2195) and its spec-only pull request through the
create-issueandopen-pull-requestskills.F11 — The PR title examples bracket the issue number; every live spec-only PR does not
Sources.
.github/skills/dev/git-workflow/open-pull-request/SKILL.md:73-78says "use Conventional Commit style, include issue reference" and its only examples are of the formfeat(tracker-core): [#42] …anddocs(agents): [#1697] …. The open spec-only pull requests #2187, #2193 and #2194 are all titleddocs(issues): add specification for #NNNN, with a trailing bare number.Symptom. A contributor following the skill produces a bracketed title that does not match its neighbours in the PR list; one following the examples departs from the skill's only stated form. The merge tool copies the title into the merge subject, so the inconsistency lands in history.
Proposed resolution. The skill states the spec-PR form explicitly, either as a third example (
docs(issues): add specification for #N) or with one sentence saying the bracketed form is for implementation PRs that carry the[#N]tag.F12 — Step 4 of
create-issuenames three of the frontmatter fields that change at filing, not all of themSources.
.github/skills/dev/planning/create-issue/SKILL.md:209-231(Step 4) says to updatespec-path, "all internal artifact references", and "any issue number placeholders". Every filed spec (for exampledocs/issues/open/2183-adopt-calendar-msrv-policy/ISSUE.md:4,7,11) also changedstatus: draft→open,github-issue: null→ the number, andlast-updated-utc; thebranchvalue's-specform is stated only in Step 6 item 2.Symptom. The fields that must change at filing are discoverable only by diffing an example; a spec filed by following Step 4 literally still reads
status: draftandgithub-issue: null.Proposed resolution. Step 4 enumerates the fields:
status,github-issue(bare number, the form all filed specs use),spec-path,last-updated-utc, and a cross-reference to Step 6 item 2 forbranch.F13 — Filed specs disagree on what the first workflow checkpoint records after the move
Sources.
docs/issues/open/2175-merge-tool-symlink-exceptions/ISSUE.mdkeeps "drafted indocs/issues/drafts/…" after filing;docs/issues/open/2183-adopt-calendar-msrv-policy/ISSUE.mdrewrites it to "drafted and moved todocs/issues/open/2183-…/ISSUE.md".docs/templates/ISSUE.mdcarries only the drafts form.Symptom. One convention leaves a dead path in every filed spec (the drafts folder no longer exists after the move, so link checkers and readers both hit a path that resolves to nothing); the other rewrites history the checkpoint was recording. Two live examples, no rule.
Proposed resolution. The template's first checkpoint reads "drafted and moved to
docs/issues/open/{number}-{short-description}/ISSUE.md", or Step 4 states the rewrite; #2195 follows the 2183 form.da2ce7 commentedon Sep 11, 2026
Frictions F14–F15 from the review of #2207 (archive of 19 closed specifications), 2026-09-11 — both about the frontmatter contract this issue owns.
dev/planning/cleanup-completed-issuesstep 6 ("confirm that every changed Markdown frontmatter block is valid YAML") is too weak to protect the edit the skill mandates. In chore(issues): archive closed issue specifications #2207 theopen/→closed/reference repair left onerelated-artifactsitem indented two spaces deeper than its siblings in five files. That is valid YAML: the over-indented line folds into the preceding scalar, so the parse succeeds and the list silently loses an entry (the 1588 spec goes from 12 entries to 11, with the closed-1586 path glued onto the task-inventory path). The check should compare the parsed item count against the raw-line count, or reject a sequence item indented deeper than its predecessor.linter markdown,linter cspellandlinter lycheeall pass on a tree with corruptedrelated-artifactsblocks, anddevelopalready carries three of them from earlier edits:docs/issues/closed/999-1978-optional-database-configuration/persistence-unavailable-scenarios.mdline 12,tests/AGENTS.mdline 8, anddocs/issues/drafts/1488-si-11-migrate-http-tracker-token-lifecycle/ISSUE.mdline 23 (an item at indent 7 following siblings at indent 5 in each). Alinter frontmattersubcommand that parses every spec's block and checks list shape and thespec-path/status/github-issuefields would catch both this and the drift the folder-style migration is trying to remove.da2ce7 commentedon Sep 11, 2026
Friction F30 from round r3 of #2207 (2026-09-11), about the frontmatter contract this issue owns.
dev/planning/cleanup-completed-issuesStep 4 states two rules that collide on the same file without saying which governs. Lines 195–197: "Do not rewrite immutable historical records (for example, past PR review summaries) merely because they accurately record the path that existed at the time. Update them only when they function as a live navigational reference." A past PR review summary such asdocs/copilot-pr-reviews/pr-2153-copilot-suggestions.mdis both: its body table records where a file sat when the thread was opened (historical), while its frontmattersemantic-links.related-artifactsis the document's machine-readable pointer at the artifacts it relates to (live navigation the moment anything walks the links). chore(issues): archive closed issue specifications #2207 resolved it the right way in5bf2ff44— frontmatter repaired, body left alone — but only after a review round was spent on the ambiguity, and the step gives a later editor no reason to land on the same split. One sentence would settle it: frontmattersemantic-linksare always repaired; body text recording a path at a point in time is never rewritten. This is the same file class F14 covers, seen from the other side: F14 is about the repair being silently wrong, F30 about the rule being silent on whether to repair.docs(docs): [torrust#2159] adopt folder-style durable records
docs(pr-reviews): migrate audit records (torrust#2159)
docs(issues): migrate draft specs to folder records (torrust#2159)
docs(issues): migrate first closed archive batch (torrust#2159)
docs(issues): migrate second closed archive batch (torrust#2159)
docs(issues): migrate third closed archive batch (torrust#2159)
docs(issues): migrate closed archive batch four (torrust#2159)
docs(issues): complete folder-style issue spec migration (torrust#2159)
fix(docs): remediate folder-style record review findings (torrust#2159)
Merge torrust#2267: docs(docs): [torrust#2159] adopt folder-style art…
chore(issues): archive closed issue specs torrust#2157, torrust#2159, t…
Merge #2340: chore(issues): archive closed issue specs