docs(corpus): add concept template - #1533
Conversation
tucktuck101
left a comment
There was a problem hiding this comment.
Review — concept template
The Good Docs Project attributions hold verbatim and the Diátaxis positioning is applied
correctly. Three gaps, and the first one means an instance built strictly from this template's
list violates the governing AGENTS.md.
Medium — the required-section list omits the corpus's own mandatory scope section
The list is Title / Definition / Visual aid / Background / Use cases / Comparison / Related
resources — which, as the node says, "follows the Good Docs Concept template's own layout". It
does exactly that. What it does not do is adapt it to this corpus.
AGENTS.md step 8 requires every node's body to carry "a scope section carrying two distinct
things: what the node does not cover and who owns it, and — separately — what you expected to
verify ... and could not", and warns that an earlier version naming only the first left step 3's
third category nowhere to go. Both siblings carry it as a numbered required item
(glossary-term.md:245-250, reference.md:253-255).
I confirmed the omission mechanically: grepping items 1-7 for omission|does not cover returns
zero. (This node itself has ## Scope and omissions at :340 — it is the instruction to
instance authors that drops it.) An instance built strictly from this list is schema-valid but
fails review against AGENTS.md. Add it as item 8, citing step 8.
Medium — "or term" claims #1537's subject with no disclaimer
The opening sentence scopes this node to "an idea, abstraction, mechanism or term in the Buzz
system". Grepping the whole node for 1340 and glossary returns zero hits, so nothing hands
that case off.
#1537 (glossary-term) is the template built for a single term — a term statement carrying the
exact written form the kebab-case id cannot express, plus a one-to-three-sentence definition —
and it disclaims in one direction only, routing discursive term material up to #1331. So an author
with "the h tag" to write finds two templates that both accept it and one that hands it off, and
the two produce different node shapes for the same subject. Owner is #1537. Strike "or term" and
add a | A single defined term and its citable definition | #1340 | row to the gap table.
Medium — instance type guidance exists only in the ledger
The reasoning is at :31 ("...may take a type value other than governance, decided by that
instance's own subject against PRD #602's corpus-surface list") and nowhere in the body; grepping
the body for type returns only the schema-enum mention. Both siblings surface it as a body
section (glossary-term.md:296-307, reference.md:214-228). With type: governance sitting in
this template's own frontmatter as the only visible example and no body text contradicting it, an
agent will most plausibly copy governance into a concept node about a relay-protocol idea — a
legal enum value, so nothing fails, but the wrong surface. Promote :31 into a short body section.
Low — the license discrepancy is attributed to the host move, not the relicensing
The body frames the 0BSD-versus-MIT-0 discrepancy as a consequence of the canonical home moving
hosts, and the INFERENCE at :159 rests on the same reasoning. The actual cause is dated: The
Good Docs Project relicensed from Zero-Clause BSD to MIT-0 with the v1.3 "Friendship" release,
announced 2024-12-12. Sibling glossary-term.md:81 states exactly this and lands the sharper
diagnosis — the research note's claim was already stale when written, not merely pointed at the
wrong host. Nothing here is literally false, but a future author learns "cite GitLab, not GitHub"
instead of "the license changed in December 2024."
Not findings, ruled out on evidence
- Index registration: the corpus
AGENTS.mdandREADME.mdboth state that indexes are
generated derived views, never hand-authored, and the ten-step "Creating a node" procedure has
no registration step. All 26 template PRs leavingAGENTS.mduntouched is correct. - CI green at head (latest run per check); node validates clean.
Reviewed by tucktuck101's review lane. Every failing claim reported above was reproduced by me against this PR head before posting.
What
Adds
launchpad/docs/corpus/templates/concept.md(id: corpus-template-concept)— the corpus template for a concept-typed documentation node, per PRD #605.
Closes #1331
Issue type
Task
Note on this issue's definition of done
Issue #1331's checklist carries a MUST/SHOULD/enforcement/exception block copied
verbatim from the standards-track issues (the ones that produced
standards/confidence.mdandstandards/decision-references.md). That checklistdescribes a policy/standard node, not a template. This node is built against
#605's actual template acceptance criterion instead: every template states its
purpose, required sections, evidence expectations and the industry model/standard
it adapts. The rest of #1331's checklist (one hand-authored document, schema-valid
front matter, one independently maintainable idea, traceable FACT/INFERENCE/
TEAM_KNOWLEDGE claims, links instead of duplication, checked against the recorded
revision, clean validator run) is generic to any corpus node and is honoured as
written. The document's own "Scope and authority" section states this same note in
place.
typechoiceUsed
type: governance.node.schema.json's enum (PRD #602's corpus-surfacelist) has no
templateorpolicyvalue. Every other corpus meta-document at therecorded revision —
AGENTS.mdexcepted, which istype: agent— usestype: governance:README.md,standards/confidence.mdandstandards/decision-references.mdall do. Noted in the node's own evidence ledgerthat a real instance written from this template takes whatever
typeits ownsubject warrants against PRD #602's list — this template document itself is not
such an instance.
Relationships
Declared none, and checked before deciding that rather than assuming it.
git ls-tree -r --name-only origin/launchpad -- launchpad/docs/corpusat commita44cf52fc740ebebbdd671427480d14f0bce0115shows exactly four validated contentnodes:
corpus-agents,corpus-readme,corpus-standard-confidence,corpus-standard-decision-references(schema/excluded from validation). Nonehas documentation forms, Diátaxis, the Good Docs Project or corpus templates as
its subject, so an edge to any of them would duplicate what the evidence ledger
already cites directly rather than add a substantive typed relationship. The
document's own "Scope and omissions" section names the likeliest future edges
(
referencesto the reference (#1346) and procedure (#1345) sibling templatesonce they merge — both siblings are being authored in parallel with none of
#1331/#1336/#1340/#1346/#1351 merged when review starts, so none targets any
other in this batch).
Research grounding
Grounded in two primary sources, both fetched directly rather than trusted from
summary:
https://diataxis.fr/explanation/,https://diataxis.fr/reference/) — fetched directly; confirms the quotes inSerina's research note (
launchpad/Research/project-documentation-templates.md,unmerged PR docs(research): industry-standard project documentation templates, tiered by what actually backs them #1466, cited
TEAM_KNOWLEDGEonly, per its own status) and adds theexplicit reader-facing contrast used for the boundary section against sibling
task: define the reference corpus template #1346 (reference): Explanation "permits reflection" and "is
understanding-oriented"; Reference is "technical descriptions of the machinery
and how to operate it" and "is information-oriented."
real correction to the research note, independent of the MADR naming error a
batch-1 agent already found: the note cites the templates repo's license as
Zero-Clause BSD from
github.com/thegooddocsproject/templates, but that GitHubrepository is archived (
archived: true, last push 2022-09-18) and theproject's live canonical home moved to
gitlab.com/tgdp/templates, whose currentLICENSEis the MIT No Attribution License (MIT-0), not Zero-Clause BSD.Both are unrestricted, no-attribution licenses, so this changes which license
text to cite, not whether the template may be reused here. Recorded as a
FACT/FACT/INFERENCE chain in the node's own evidence ledger rather than silently
fixed, the same way batch-1 handled the MADR naming error. The template's
required-sections structure (
concept/template_concept.md) and scope guidance(
concept/guide_concept.md) were fetched from the live GitLab repo.Boundary against sibling templates
Stated explicitly in a dedicated "Boundary against reference (#1346) and procedure
(#1345)" section, per the batch brief: concept/explanation is
understanding-oriented, reference is information-oriented (Diátaxis's own
contrast); a concept node answers "what is this and why does it matter," a
reference node answers "what are its exact parameters." Also notes, without
attempting to resolve, the boundary against procedure/how-to content (#1345,
outside this batch).
Validator + verify-gate evidence
Both run unpiped, as the literal last commands before
git commit.Review
Codex (cross-model) is down, tracked as #1467. Same-model adversarial self-review
substituted: re-read the full node against
AGENTS.mdafter drafting and found onereal blocker — an evidence entry citing two GitHub issue URLs as
FACT, whichAGENTS.mdexplicitly forbids ("an issue URL is an external URL... Do not force itinto a FACT on a tool-result or URL citation. Use TEAM_KNOWLEDGE with
provided_bynaming the issue"). Fixed before this PR was opened — reclassified to
TEAM_KNOWLEDGE. Also caught and corrected an imprecise date-recency claim("the day before" → the actual two-day gap between the GitLab project's last
activity and this node's recorded revision).
Escalations
None filed. No findings surfaced outside this node's own scope during drafting or
self-review.