docs: add the authoring guideline and the architecture decision records - #627
Draft
gbrlcustodio wants to merge 3 commits into
Draft
docs: add the authoring guideline and the architecture decision records#627gbrlcustodio wants to merge 3 commits into
gbrlcustodio wants to merge 3 commits into
Conversation
This was referenced Aug 12, 2026
gbrlcustodio
marked this pull request as ready for review
August 12, 2026 18:54
gbrlcustodio
force-pushed
the
docs/decisions
branch
from
August 12, 2026 19:26
b45fb3d to
7eb5f66
Compare
gbrlcustodio
force-pushed
the
docs/decisions
branch
from
August 12, 2026 19:55
7eb5f66 to
f7fda84
Compare
gbrlcustodio
force-pushed
the
docs/decisions
branch
2 times, most recently
from
August 12, 2026 20:10
0f04db5 to
5f4acbb
Compare
gbrlcustodio
force-pushed
the
docs/decisions
branch
from
August 12, 2026 20:30
5f4acbb to
ae7ec49
Compare
gbrlcustodio
force-pushed
the
docs/decisions
branch
from
August 12, 2026 20:47
ae7ec49 to
64fe164
Compare
gbrlcustodio
force-pushed
the
docs/decisions
branch
from
August 12, 2026 20:52
64fe164 to
6d9f3ab
Compare
gbrlcustodio
force-pushed
the
docs/decisions
branch
from
August 12, 2026 21:39
6d9f3ab to
d5437a5
Compare
gbrlcustodio
force-pushed
the
docs/decisions
branch
from
August 12, 2026 21:51
d5437a5 to
0df5f6f
Compare
gbrlcustodio
force-pushed
the
docs/decisions
branch
from
August 12, 2026 22:06
0df5f6f to
b7fc2c9
Compare
gbrlcustodio
force-pushed
the
docs/decisions
branch
from
August 12, 2026 22:16
b7fc2c9 to
a745e6a
Compare
gbrlcustodio
force-pushed
the
docs/decisions
branch
from
August 12, 2026 22:21
a745e6a to
e6da5eb
Compare
gbrlcustodio
force-pushed
the
docs/decisions
branch
from
August 12, 2026 22:38
e6da5eb to
cd03e20
Compare
gbrlcustodio
force-pushed
the
docs/decisions
branch
from
August 13, 2026 16:06
639a717 to
46e7bc0
Compare
gbrlcustodio
force-pushed
the
docs/decisions
branch
2 times, most recently
from
August 13, 2026 19:44
3f0f95a to
fedb77c
Compare
gbrlcustodio
force-pushed
the
docs/decisions
branch
from
August 13, 2026 19:54
fedb77c to
aab59dc
Compare
gbrlcustodio
force-pushed
the
docs/decisions
branch
from
August 13, 2026 20:15
aab59dc to
bd23da2
Compare
gbrlcustodio
force-pushed
the
docs/decisions
branch
from
August 13, 2026 20:25
bd23da2 to
0f02db7
Compare
gbrlcustodio
force-pushed
the
docs/decisions
branch
from
August 13, 2026 20:29
0f02db7 to
0ff89e1
Compare
gbrlcustodio
force-pushed
the
docs/decisions
branch
13 times, most recently
from
August 14, 2026 23:49
6d87a88 to
32c6b11
Compare
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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