docs(corpus): add procedure corpus template - #1539
Conversation
Adds launchpad/docs/corpus/templates/procedure.md, the how-to/procedure template for PRD #605, grounded in Diataxis's How-to guide form and the Good Docs Project's How-to template (verified as MIT-No-Attribution, not the Zero-Clause BSD an unmerged research note claims). States the reference/how-to boundary from this side, coordinating with the sibling corpus-template-reference node (#1346, PR #1534) rather than restating it. Closes #1345 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 — procedure corpus template
Diátaxis how-to grounding is accurate — eleven passages quoted verbatim and correctly applied. Three
findings, one of which would make the template reject a legitimate how-to.
Medium — references has an authored inverse, and the body promises a generated one
The FACT at :26-29 says references has "a generated inverse named referenced-by", and
:400-404 tells an instance author it may declare references toward the template "if the author
wants the generated referenced-by edge".
relationships.schema.json sets relationshipMeta.references to
{"inverse": "authored", "inverseType": "referenced-by"} — the only one of the five whose
inverse is not generated. schema/README.md:64-67 defines the distinction: authored means "a
human writes both directions", generated means "tooling derives the reverse edge; never write it
by hand". So an author following :400-404 declares the forward edge and waits for a reverse edge
no tooling produces. Sibling #1534 has the same inversion; #1533 and #1537 state it correctly.
Medium — required section 3 forbids the forking how-to Diátaxis explicitly allows
Section 3 mandates "One numbered task sequence per logical goal ... numbered in the order they must
be performed". diataxis.fr/how-to-guides/, under "What how-to guides are not", says:
"solving a problem or accomplishing a task cannot always be reduced to a procedure. Real-world
problems do not always offer themselves up to linear solutions. The sequences of action in a
how-to guide sometimes need to fork and overlap, and they have multiple entry and exit-points."
This node quotes eleven other passages from that same page and omits this one — in a template named
procedure. As written it rejects a legitimately branching how-to as malformed. Add the
fork/branch/judgement allowance to section 3, quoting the passage.
Medium — four templates, four answers for the instance-to-template edge
This node says an instance "may declare references" toward its template.
relationships.schema.json gives "a template instance of a standard" as the worked example for
implements, and two siblings in this wave use it: runbook.md:252-255 ("should declare ...
{type: implements, target: corpus-template-runbook}") and threat-model.md ("must declare
implements"). deployment.md is silent entirely.
My ruling for the wave: implements, stated as a SHOULD. It matches the schema's own example,
and #607's criterion ("every node ... uses the assigned template") argues for the stronger form.
Aligning is worth one line in each.
Low — a FACT the body then contradicts
The entry asserts "No open or closed launchpad-26/buzz issue matches a search for a corpus template
task covering Diátaxis's Tutorial form", backed by two tool-result citations returning []. The
body at :225-226 and the omissions table at :459 then say the gap was "filed as #1538" — and
#1538 is open, "task: corpus templates do not cover Diátaxis's Tutorial form", opened the same day.
The two are reconcilable in sequence (searched, found none, then filed one) but the FACT is false at
the PR's own head. Append "...at the time of the search; #1538 was then filed to own it."
Boundary ruling
"Cut a relay release" -> procedure. "Relay is 5xx-ing, what do I do" -> runbook. Genuinely
distinct, no duplication — but your Boundary section omits runbook (#1347) entirely, and runbook's
overflow pointer sends the general-operations case to a nonexistent node shape rather than here. One
bullet each.
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/procedure.md, the how-to/procedure corpus template for parent Feature #605, grounded in Diátaxis's How-to guide form and the Good Docs Project's fillable How-to template. States the reference/how-to boundary from the procedure side, coordinating with the siblingcorpus-template-referencenode (#1346, PR #1534) rather than restating it from scratch.Related issue
Closes #1345
Issue type
Task
Agent provenance
Objective
Create
launchpad/docs/corpus/templates/procedure.mdas the canonical corpus node stating the required sections, evidence expectations, and industry model for a how-to/procedure-shaped corpus document.Impacted components
Approach and rejected alternatives
Modeled the node's structure on the already-open sibling
corpus-template-reference(#1346, PR #1534) for internal consistency across the batch (Scope and authority / Industry model / Boundary / A note ontype/ Required sections + skeleton / Evidence expectations / Relationships / Note on Definition of Done / Scope and omissions).Rejected alternatives:
diataxis.fr/how-to-guides/page today (the page's own words are "A how-to guide helps the user get something done, correctly and safely; it guides the user's action" plus "serves the work of the already-competent user"). Rejected citing the note's phrasing as a direct Diátaxis quote; instead fetched the live page directly for FACT-class quotes and cited the note's paraphrase separately asTEAM_KNOWLEDGE.gitlab.com/tgdp/templates/-/raw/main/LICENSEdirectly: it is the MIT No Attribution License, not 0BSD. Two prior corpus-template batches independently caught this same error; verified it again from the primary source rather than trusting either the note or the prior batches' restatement.template/procedurevalue fortype. Rejected —node.schema.json'stypeenum has no such member; usedgovernance, the confirmed precedent across all ten batch-1/batch-2 template nodes.referencesrelationship tocorpus-template-reference(task: define the reference corpus template #1346), since the two templates discuss each other in prose. Rejected — task: define the reference corpus template #1346 is not yet merged intoorigin/launchpad, andAGENTS.mdrequires relationship targets to resolve against the merge-target branch, not the author's own worktree.Verification
Command run:
Raw output:
The 22
UNVERIFIEDnotices are the expected non-fatal notices for commit/tool-result/external-URL citation shapes perAGENTS.md's own citation-shape table (5 from the three pre-existing nodes, 17 from this node's own commit/tool-result/external-URL citations) — none are errors.Command run (verify-gate, run as the literal last command before
git commit, nothing piped or redirected):Raw output:
Not verified
#1346's eventual merged text draws the reference/how-to boundary identically to how this node draws it from its own side. Checked against PR docs(corpus): add reference corpus template #1534's current (unmerged) body only; neither task: define the reference corpus template #1346 nor this node had merged as of this writing, so the merged text could differ.just corpus-validate(the Hermit-wrapped form) — ran the directpython3 launchpad/project-intelligence/corpus/validate.pyinvocation instead, perAGENTS.md's own statement that the two are equivalent and the direct form needs no environment activation.Security implications
None — this is a documentation-only change to a Markdown corpus node with no executable code, secrets, or configuration affecting runtime behavior.
Escalations
gh issue list --search "corpus template tutorial"and"corpus-template-tutorial", both empty) before filing. This is the same category of gap the siblingcorpus-template-referencenode (task: define the reference corpus template #1346, PR docs(corpus): add reference corpus template #1534) found for API Reference depth and filed as task: corpus templates do not distinguish plain Reference from API Reference #1532.Cross-model review unavailable: Codex is down, tracked as #1467. Same-model adversarial self-review substituted — re-read the drafted document against its own evidence ledger and the Diátaxis/Good Docs Project primary sources for internal consistency, and caught two issues before committing: (1) a markdown bullet under Evidence expectations was accidentally nested one level under the previous bullet rather than being its own top-level item; (2) the Required sections item on the Boundary statement claimed "three exclusions" while the Boundary section actually lists four (the fourth, about
AGENTS.mditself, is specific to this template node's own self-awareness and doesn't recur in an instance node) — reworded to make that distinction explicit rather than leave an uncorrected miscount, the same class of drift bugAGENTS.mditself warns about.