Skip to content

docs: add the authoring guideline and the architecture decision records - #627

Draft
gbrlcustodio wants to merge 3 commits into
docs/architecture-principlesfrom
docs/decisions
Draft

docs: add the authoring guideline and the architecture decision records#627
gbrlcustodio wants to merge 3 commits into
docs/architecture-principlesfrom
docs/decisions

Conversation

@gbrlcustodio

@gbrlcustodio gbrlcustodio commented Aug 12, 2026

Copy link
Copy Markdown
Member

Why

A living document holds the rule that a contributor follows today. A record holds the reasoning that produced that rule. A living document changes as the code moves, and an adopted record does not change. The split keeps the durable reasoning out of the file that goes stale.

The docs tree also stated no rule for where a new document goes. A contributor had to infer the rule from the tree, and an inferred rule produces a misplaced document.

Outcomes

  • Four decision records ship. Each one links to the living document that carries its rule, and the index maps every record to that document.
  • Every record ships as proposed, because the code does not match the records yet. A proposed record stays editable in place. After adoption, a record becomes immutable, and only a later record can supersede it. A decision that reads wrong is therefore cheap to correct now.
  • One record carries no living rule, because its decision stays deferred. That is a property of a deferred decision, and not a gap in the set.
  • One guideline states where a new document goes, by audience and by kind. It also states the form of a convention, so the next rule arrives as a rule and not as a paragraph.
  • The guideline rules on where a gap is documented. A convention states practice, so older code that predates it is legacy and the convention names no gap. The map states a claim about the code, so the map owes the reader every deviation.
  • The map gains a back-link to each record that explains one of its decisions. A reader who asks why a decision holds reaches the reasoning in one step.
  • The MCP reference gains the tool-design section that the map points to.
  • This PR changes documentation only. No code path and no test path changed.

@gbrlcustodio
gbrlcustodio marked this pull request as ready for review August 12, 2026 18:54
@gbrlcustodio gbrlcustodio self-assigned this Aug 12, 2026
@gbrlcustodio
gbrlcustodio force-pushed the docs/decisions branch 2 times, most recently from 0f04db5 to 5f4acbb Compare August 12, 2026 20:10
Add docs/contributing/authoring.md, which records where a doc belongs in
the docs/ tree: audience first, then Diataxis kind. Add the four
consolidated records under docs/contributing/adr/: layered
responsibility, typed single-form contract, MCP tools express outcomes,
and vertical-slice structure. An index README maps each record to the
living doc that holds its current rule.

Give authoring.md a section on writing a convention, so the rule form in
conventions.md has an owner: the permanent ID, the Do and Do not lists,
the three-sentence cap on the reason, the bar that a rule corrects
something that happened, and the ban on naming a shipped symbol in an
example.

Add a section on where a gap is documented, split by the kind of doc. A
convention governs the next change, so conventions.md names no gap and
older code is legacy rather than a shortfall. architecture.md is a map,
and a map claim is either true of the code or not, so its deviations
gather in one Known gaps section where each entry names the artifact
that closes it, such as an import-linter contract that is written and
disabled. Neither doc carries the inventory or the plan, because a
concrete step is closeable work and belongs in an issue, which is what
this file already says for a misplaced doc and a cleanup step.

All four records land as proposed. A fact-check against the code found
that no record is adopted yet, so the set stays one editable proposal
until each rule is true of the code.

Link each record from the living doc that carries its rule, and add to
docs/mcp/README.md the tool-design section that architecture.md points
to.

Record that ADR-0004 has no living rule while it stays deferred. Both
the record and the index pointed at architecture.md, which no longer
carries a deferred restructure section, so both pointers were false.
architecture.md maps the horizontal structure that holds today, and
this record is the only place that describes the target.

Link the index itself, which nothing in the repository linked. Three
records were reachable only from the one section in architecture.md that
cites each, and ADR-0004 was reachable by no path at all, because it
holds no rule and so earns no back-link. One pointer in the intro covers
every record and each one added later.

Record where ADR-0004's slice names come from. They are the sub-domains
of Pipefy's own domain model, maintained outside this repository, so a
slice boundary follows a boundary that the business already draws. The
record carried the list without its source, which left the names reading
as a choice made here.

Signed-off-by: Gabriel <gabriel.custodio@pipefy.com>
Signed-off-by: Gabriel <gabriel.custodio@pipefy.com>
Signed-off-by: Gabriel <gabriel.custodio@pipefy.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant