Skip to content

docs: cut the Workflow section to what nothing else supplies - #77

Merged
lesnik512 merged 1 commit into
mainfrom
docs/trim-workflow-duplication
Sep 6, 2026
Merged

docs: cut the Workflow section to what nothing else supplies#77
lesnik512 merged 1 commit into
mainfrom
docs/trim-workflow-duplication

Conversation

@lesnik512

Copy link
Copy Markdown
Member

Why

The Workflow section states three things this repo already states elsewhere, and
AGENTS.md is loaded on every turn.

The ADR and issue routes are written twice. docs/agents/domain.md
already says "a rejected alternative → an ADR; real work you are not doing now → a
GitHub issue. Nothing else gets written", and then points back here for the admission
check. docs/agents/issue-tracker.md owns the gh
usage. The circularity is the tell.

NNNN-slug.md, sequential is supplied by the domain-modeling skill's ADR format,
which is what docs/agents/domain.md configures. Restating it here means it rots in
two places at once, which is what the same file warns about four sections down.

"There is no change file, no lane to choose, and no planning/ tree" describes
three directories that do not exist. Derivable from the source, therefore not written.
The same goes for "no truth-home directory".

Design

Cut to what nothing else supplies:

Nine lines become seven, and the two duplications become one pointer.

Non-goals

  • Not removing the revisit-trigger rule. Delete the local PR templates; keep the generic org default #53 decided not to
    propagate it to the other repos. Removing it here is a change to this repo's own ADR
    practice and is a separate call.
  • Not touching docs/agents/. The pointer direction is AGENTS.mddocs/agents/;
    the reverse pointer in domain.md (back here for the admission check) is correct,
    since the admission check has no other home.
  • Not touching the Where a fact goes table. Its docs/adr/ row overlaps the
    Workflow paragraph, but the table is the admission check itself and is load-bearing.

Verification

uv run pytest: 123 passed, 26 skipped, 5 failed. The five are PNG rendering and
reproduce unchanged on mainrsvg-convert and pngquant are not installed
locally; CI installs them. This change touches no Python.

The one new link, docs/agents/, is a directory that exists and is already linked
the same way from this file's Agent skills section. The links job (offline lychee
over **/*.md) is the gate.

@lesnik512
lesnik512 merged commit f48f134 into main Sep 6, 2026
3 checks passed
@lesnik512
lesnik512 deleted the docs/trim-workflow-duplication branch September 6, 2026 17:30
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