docs(corpus): launchpad/docs/corpus/templates/component.md -- the component corpus template - #1551
Conversation
…ponent corpus template (#1330) Adds the component corpus template: how to document one software component (a crate, or a cohesive module inside one) as a standalone knowledge artifact -- responsibility, public interface, and real dependency edges -- distinct from #1326's architecture-component template, which decomposes one container with a required diagram. Grounds its industry model in this repository's own rustdoc crate-level/item-level doc-comment convention (verified against doc.rust-lang.org primary sources) rather than reaching for C4/arc42 again, since the unmerged research note independently calls arc42 too heavy for a single crate. Closes #1330 Signed-off-by: Serina Mcfall <serina.mcfall@gmail.com>
tucktuck101
left a comment
tucktuck101
left a comment
There was a problem hiding this comment.
Review — component corpus template
On the duplication question first, unhedged: component.md is NOT a duplicate of
architecture-component.md. They own different granularities — one node per component at
implementation altitude here, one node per container at architecture altitude there — and this
node's Boundary section addresses the collision head-on and by name. What is missing is a
link-don't-restate rule, below. One false claim about this repository.
High — the "30/30 crates" claim that justifies the rustdoc model is false
:140-142 states the rustdoc convention is one "this repository's own source already follows for
every one of its 30 crates at some level. A crate-level //! doc comment at the top of
lib.rs states the crate's responsibility", and later "30/30 crates carry crate-level docs at
some level, 12/30 enforce coverage on public items".
Measured on launchpad: ls -d crates/*/ is 30, but only 26 contain src/lib.rs —
buzz-admin, buzz-backend-kubernetes, buzz-pairing-cli and sprig have none. The weaker
reading also fails: crates/sprig/src/main.rs begins fn main() { and contains zero //!
lines. True figure is 29 of 30; the lib.rs mechanism holds for 26 of 30.
This is the entire stated reason for grounding the template in rustdoc rather than C4/arc42, and the
premise of its strictest rule — "A responsibility claim is a FACT or nothing. Cite the component's
crate-level doc comment" — so an author writing a sprig node follows a template asserting such a
comment always exists. No evidence entry supports the count, unlike the frontmatter's other crate
censuses (READMEs at :41-47, missing_docs at :55-61), both of which I verified as exactly
correct. Say 29 of 30, drop "at the top of lib.rs" as universal, and add an evidence entry — the
design decision survives intact.
Medium — nothing tells the container-level row to link rather than restate
architecture-component.md:239-243 requires, per building-block row, "name, responsibility (one
sentence), its interface/contract, and the evidence citation for its existence". This node's
required sections 2 and 3 require Responsibility and Public interface with citations for the same
object. For any component with both nodes, the same three facts are mandatory content in two places
with no precedence rule. :184-186 gestures at it ("may optionally be the deeper detail behind one
row") but neither template says the row links rather than restates.
The corpus AGENTS.md says a second copy "drifts silently", create-step 2 is "Check nothing already
covers it", and #1330's DoD requires linking neighbours "without duplicating their canonical
content". Ownership: architecture-component owns the container-scoped decomposition; component owns
the per-component node. The missing instruction belongs here.
Low — the Boundary section never separates the two senses of "component"
This node uses "component" to mean "a crate, or a cohesive module inside one" (:104-105, :141),
while its three C4-grounded siblings use C4's sense — under which "a Java JAR, C# assembly, DLL,
module, package, namespace, folder etc" is "Perhaps but, again, typically not" a component
(c4model.com/abstractions/component FAQ, which I read in full). One sentence naming the two senses
apart removes the residual pick-wrong risk.
Low — an unmerged sibling path is presented as resolvable
The "For / Read" table routes readers to
launchpad/docs/corpus/templates/architecture-component.md as a resolvable path. This PR adds
exactly one file, and that path exists neither here nor on the integration branch. You do disclose
#1326's unmerged status in three other places, so this is internal presentation inconsistency, and
it self-resolves if #1528 merges.
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.
2 participants
Summary
Adds
launchpad/docs/corpus/templates/component.md, the template for documenting one software component (a crate, or a cohesive module inside one) as a standalone knowledge artifact. It draws an explicit boundary against#1326's already-drafted architecture-component template and grounds its industry model in this repository's own rustdoc convention rather than reaching for C4/arc42 a second time.Related issue
Closes #1330
Issue type
Task
Agent provenance
Objective
Create
launchpad/docs/corpus/templates/component.mdas the corpus template a future component-scale node is written against.Impacted components
Approach and rejected alternatives
Read PR #1528's actual diff first (
git show origin/task/1326-corpus-template-architecture-component:launchpad/docs/corpus/templates/architecture-component.md), since#1326is the highest-overlap sibling in this batch.#1326is titled "architecture-component" and is tightly scoped to the C4 model's Component diagram: one container's internal decomposition, a required Mermaid diagram,type: architecture, requiredpart-oftoward the container.#1330is titled plainly "component" with no "architecture-" prefix — a real signal it is a different, broader node.Checked this repository's own precedent before reaching for an external framework, per the batch brief's instruction:
README.md, each shaped as an install/usage guide (Install, Authentication, Usage, Configuration) — real precedent, but inconsistent coverage and not systematically responsibility/interface/dependency shaped.src/lib.rscarries a//!crate-level doc comment stating its responsibility, and 12 of 30 crates additionally enable#![warn(missing_docs)], enforcing doc coverage on public items — a much more widespread, tooling-adjacent convention.Cargo.toml[dependencies]sections give real, structural, verifiable evidence for a component's dependency edges in both directions.Chosen approach: ground the template in this repository's own rustdoc convention (crate-level
//!docs, item-level///docs,Cargo.tomldependency manifests), verified againstdoc.rust-lang.orgprimary sources, rather than C4/arc42 a second time. The unmerged research note (#1466) independently supports this: "arc42 is too heavy for a component. Twelve sections on a single crate produces ten empty ones." — naming a single crate as its own example of component scale.Rejected alternative: reusing C4/arc42 again for
component, the same way#1326/#1327/#1328did for architecture-context/-container/-component. Rejected because it would be citing the same industry model for a second, narrower purpose it was not designed for, and because this repository already has a real, working, in-tree documentation convention for exactly this subject that the C4/arc42 approach would ignore.Boundary drawn against
#1326(stated explicitly in the node's own Boundary section): a component node documents one component standing alone — no required diagram, no container decomposition — and its validity never depends on an architecture-component node existing. It may optionally declarepart-oftoward an architecture-component node if one exists and names this component in its building-block table, but that is optional, not the reason the node exists.type: implementation, notarchitecture: node.schema.json's type enum has no finer-grained member than the 13 named surfaces;implementationfits a component's code-level responsibility/interface/dependency content better thanarchitecture's decomposition-and-diagram content, which#1326already claims.Verification
Command run:
Raw output:
Command run:
Raw output:
Not verified
#1326's already-reviewed shape, not in a worked instance.desktop/andmobile/have their own module conventions this node did not inspect.Security implications
None. This is a documentation-only change to a corpus template file; it adds no code, no dependencies, and no runtime behavior change.
Escalations
None. The
#1326boundary and thetype: implementationchoice are judgment calls, but each is stated and reasoned explicitly in the node's own front-matterINFERENCEentries and Boundary section rather than left silent, per the batch brief's guidance to make a real call and show the reasoning rather than escalate an intentional design decision. If a reviewer disagrees with either call, that is a request for revision on this PR, not a separate issue.