Skip to content
tack

Ask the docs

Ask anything about Tack.

Answers come from these docs, with links to the pages they’re from.

Answers are written by AI from these docs and can be wrong: check the pages they link to.

Decision records

A decision that’s been decided can be written back to GitHub. Choose Write back on it.

The dialog

Section titled “The dialog”
  • Write it as: ADR pull request (“Adds record 0002 for review”), or Discussion post (“Announces it for comment”; off if the repository has Discussions turned off).
  • Repository: the repositories of the decision’s linked cards come first. Type, or paste a link, for another.
  • Folder, for a pull request: where the repository already keeps its records (docs/decisions, docs/adr, adr and the other usual places, by which has numbered records in it), or docs/decisions. Click it in the path to change it; Tack remembers the folder you choose for each repository.
  • Context, Decision and Consequences: start from the decision’s body and title. They’re written onto the decision as you type, so nothing is lost if you cancel or the push fails, and the decision on the board shows its consequences. A preview of the record sits beside them.
  • For a Discussion, the Category: one called something like “Decisions”, “ADR” or “RFC” if there is one, then “Announcements”, then “General”.

Stage write-back stages it with the board’s other changes. The decision shows “ADR 0002 · Staged”, then “Pushing…” and “Confirming…” while it’s pushed.

ADR pull requests

Section titled “ADR pull requests”

The record is a Markdown file in the repository’s records folder (docs/decisions/ unless it keeps them elsewhere), in the layout adr-tools uses:

  • Path: docs/decisions/NNNN-title-in-words.md, numbered one more than the highest record already in the folder on the default branch. Records staged on the same board count too, so two decisions pushed together don’t collide.
  • Branch: tack/adr-NNNN-title-in-words, from the default branch, with one commit adding that one file.
  • Pull request: “ADR NNNN: Title”, saying which board it was decided on, and listing the linked items.

The record itself:

# 2. Store boards as Yjs documents


Date: 2026-10-08


## Status


Accepted on 2026-10-08 (4 agree, 1 disagree)


## Context


…


## Decision


…


## Consequences


…


## Links


- [acme/app#412: Drop Node 18 support](https://github.com/acme/app/issues/412)
- Decided on [the Tack board](https://tack.example.com/b/…)

Once it’s pushed, the decision shows the pull request live, like a card: Open, then Merged when someone merges it on GitHub, with CI along the bottom.

Writing an ADR needs the app’s Contents: Read and write permission. Apps set up before Tack could write files only have read access: see Upgrading.

Discussion posts

Section titled “Discussion posts”

The post is titled “Decision: Title”, with the same record as its body. Once pushed, the decision links to it: “Posted to Discussions”.

If it fails

Section titled “If it fails”

The decision shows Write-back failed, with Retry, which opens the dialog again. Reopening a decision as proposed unstages a write-back that hasn’t been pushed.