Skip to content

Documentation bodies focus on their subject - #293

Merged
Marius Storhaug (MariusStorhaug) merged 2 commits into
mainfrom
canonical-guidance-ownership
Nov 12, 2026
Merged

Marius Storhaug (MariusStorhaug) merged 2 commits into
mainfrom
canonical-guidance-ownership

Conversation

@MariusStorhaug

@MariusStorhaug Marius Storhaug (MariusStorhaug) commented Nov 12, 2026 •

Copy link
Copy Markdown
Member

Documentation authors keep document bodies focused on the subject and leave document-maintenance records in source control and reviews. Required navigation fields stay, as do the rationale, mechanisms, contract links, and evidence that explain the subject.

Reusable instructions also follow code engineering practices. Contributors correct missing or incorrect rules in their canonical documents before updating dependent instructions, and reviewed PR merge determines when a correction becomes accepted guidance.

Changed: Documentation bodies focus on the subject, not the document

Remove self-descriptive introductions, bylines, document-owner fields, approval status, review dates, document versions, revision history, and authoring notes from document bodies. Keep the required navigation front matter, including title and description.

Keep the subject's scope, requirements, source links, design rationale, mechanisms, alternatives, and evidence. Operational ownership, product versions, observation dates, and decision status remain when readers need those facts to understand or use the subject. This is not a request to remove useful design explanations or subject data.

The general rule has one home in Documentation Model: Subject-focused content. Authoring conventions and templates reference it. Design, implementation, reference, playbook, and decisions-register placeholders now request subject content instead of page self-description. The edited standards also remove self-introductory wording.

This changes authoring guidance and the reusable templates, not product interfaces or automated enforcement. No product upgrade or migration is required. Existing documentation outside the four edited pages is not rewritten in this PR.

Technical details

The scoped PR comparison is f9b335d0b78a3eead0b7efa573936e86cb1e7265 to ff73af361768c744351d0c5353a4b79fd267ac83. The subject-focused follow-on is isolated in commit ff73af361768c744351d0c5353a4b79fd267ac83 after the original lifecycle commit.

The delivery issue records the direct follow-on scope, the confirmed navigation-field exception, and verification of ordinary instructions, design rationale, ownership, versions, observation dates, and decision records. Actual page navigation front matter and existing headings remain unchanged.

Fresh local validation passed: shared Markdown lint is clean for all four changed pages; local links resolve across 130 documentation files; all 8 cross-repository links resolve; all 66 Pester tests pass across 6 suites. The fresh automated review approved this candidate with no new inline comments.

Every current validation check reports completion and success. Publish is intentionally skipped for pull requests. A native retry resolved the earlier inconsistent Links completion state; the current Links check 131200062620 explicitly reports completed and success. No readiness gate was waived. The Docs workflow and cross-repository workflow completed successfully.

Changed surface Standards checked Framework docs checked Result
Documentation-Model.md, Spec-Driven-Development.md, Spec-Driven-Development-Templates.md under src/docs/Ways-of-Working/ Natural Language, Markdown, artifact templates, PR Format, Contribution Workflow Documentation Model; canonical authoring conventions and ownership boundaries Aligned

The scoped issue sweep covered metadata and self-description terms. No additional issue is fully satisfied. Navigation-generation and tooling-output metadata work remain separate.

The publication route in .github/workflows/Docs.yml builds and publishes the documentation site without invoking Release Management. Release metadata and labels are omitted. No integration-template change applies.

Changed: Reusable instruction changes use the code delivery process

Standards, guides, stored prompts, skills, and agent files follow the existing contribution workflow, including source control, testing and verification, pull requests, review, and acceptance. A correction becomes accepted guidance only after its pull request is reviewed, approved, and merged. One-off chat requests do not require a versioned artifact or pull request merely to receive or act on the request.

Maintainers correct a missing or incorrect rule in its owning canonical document before updating dependent instructions. Dependent entry points reference that document rather than copy its rules. This applies to every canonical document, not only PR Format. Immediate self-improvement starts a proposal; it does not bypass verification or make an unreviewed correction accepted guidance.

Technical details

src/docs/Ways-of-Working/Evolutionary-Development.md retains the instruction-maintenance section and its anchor. Its opening now describes the feedback cycle instead of the standard itself. The lifecycle and source-first changes remain isolated in the original commit a16564842877015f06d6f86b814f42d34c106a26.

The original five examples cover missing PR rules, missing rules in other canonical documents, incorrect instructions, reusable instruction changes, and one-off chat requests. The expanded candidate has its own fresh approved automated review; the earlier approval is not used to validate the new diff.

Changed surface Standards checked Framework docs checked Result
src/docs/Ways-of-Working/Evolutionary-Development.md Natural Language, Markdown, standard artifact template, PR Format, Contribution Workflow Documentation Model; Agentic Development pointer and shared-source requirements Aligned

The instruction-convergence sweep covered instruction/canonical title terms, instruction-and-code body terms, and the owning document name. No additional issue is fully satisfied. Instruction trust-boundary and diagnosis work remain separate.

This PR remains a draft, with merge and auto-merge disabled.

Related references

Copilot AI previously approved these changes Nov 12, 2026

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approved

No active review issues are reported for the documentation changes clarifying reusable-instruction maintenance.

No open issues 🎉

What changed in this PR

This PR clarifies how reusable instructions are maintained within the existing contribution workflow, without adding automated enforcement or changing product behavior.

Changes:

  • Applies code engineering practices to durable instructions while exempting one-off chat requests from source-control and pull-request requirements.
  • Clarifies that immediate self-improvement starts a proposal; guidance becomes accepted only after review, approval, and merge.
  • Requires corrections at the canonical source, with dependent instructions linking rather than copying rules.
File Description
src/​docs/​Ways-of-Working/​Evolutionary-Development.md Clarifies instruction maintenance, acceptance requirements, and canonical-source reuse while preserving the existing section anchor.

Review effort: Balanced

@MariusStorhaug Marius Storhaug (MariusStorhaug) changed the title Reusable instructions follow code engineering practices Documentation bodies focus on their subject Nov 12, 2026

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approved

No active review issues block the documentation standards and reusable template updates.

No open issues 🎉

Review effort: Balanced

@MariusStorhaug
Marius Storhaug (MariusStorhaug) marked this pull request as ready for review November 12, 2026 14:11
@MariusStorhaug
Marius Storhaug (MariusStorhaug) merged commit e0178c9 into main Nov 12, 2026
27 checks passed
@MariusStorhaug
Marius Storhaug (MariusStorhaug) deleted the canonical-guidance-ownership branch November 12, 2026 15:18
Marius Storhaug (MariusStorhaug) added a commit that referenced this pull request Nov 13, 2026
MSX guidance starts with the rules, procedures, behavior, and designs
readers need instead of unnecessary document self-description. Useful
scope, authority, rationale, and evidence stay intact. No adoption
action is required; product and process contracts do not change.

<!-- ANNOUNCEMENT STOP -->

## Changed: Guidance leads with its subject

The sweep inventories the 126 remaining authored pages and makes focused
prose edits to 53 of them: coding standards, ways of working, capability
guidance, and section introductions. Redundant introductions are
removed. Useful source and scope statements describe the subject
directly rather than describe the page.

Navigation front matter, headings, links, code samples, diagrams,
tables, and generated index regions remain unchanged. Operational
ownership, product versions, observation dates, decision status,
requirements, mechanisms, alternatives, and rationale remain subject
facts. Runtime router and template contents are unchanged.

<details>
<summary>Technical details</summary>

**Source and scope.** The accepted baseline is
`e0178c9dc2cce3c09c7792ddff5b14f761a7d9e7`, which merged
#293. The reviewed candidate is
`51db56a3425f3b9a43cbc77b49f18720b09fdf8b`. Its three focused commits
change only authored Markdown prose: 53 files, 102 insertions, and 120
deletions. The four pages covered by the earlier change are unchanged.
The reusable rule remains at its canonical source: [Subject-focused
content](https://github.com/MSXOrg/docs/blob/e0178c9dc2cce3c09c7792ddff5b14f761a7d9e7/src/docs/Ways-of-Working/Documentation-Model.md#subject-focused-content).

**Preservation.** A base-to-candidate audit confirms identical front
matter, headings and heading attributes, fenced code and diagrams,
Markdown tables, generated index regions, inline code, link
destinations, and HTML anchors across all 53 changed pages. The
inventory remains 130 pages, with four exclusions and no added, removed,
or renamed pages. Context review preserves the meaning of rewritten
scope and authority statements.

| Check | Result |
| --- | --- |
| Markdown lint | All 130 pages examined; no findings. Explicit file
paths avoid an unmatched Windows glob. |
| Local links and anchors | All links resolve across 130 pages. |
| Cross-repository links | All 8 links resolve across 134 Markdown
files. |
| Pester | All 66 tests pass across six suites; none fail or are
skipped. |
| Zensical | Exact pinned version 0.0.59 builds with no issues in an
isolated session environment. The installed 0.0.50 was not accepted as
pinned-toolchain evidence. |
| Final-commit CI | Lint, Build, Links, Test, and Cross-repository links
pass. Publish is correctly skipped for the pull request. |
| Automated review | Explicit Copilot round approves the exact candidate
commit with zero inline comments; no review threads remain. |

CI evidence:
[Docs](https://github.com/MSXOrg/docs/actions/runs/43250352973) and
[Cross-repository
links](https://github.com/MSXOrg/docs/actions/runs/43250352618).

The delivery issue's inventory, baseline checks, three content slices,
preservation audit, local validation, final diff review, and convergence
pass are complete. No product implementation or integration-template
change is required because the supported contracts and executable
examples are unchanged. The Pages route does not invoke versioned
Release Management.

| Changed surface | Standards checked | Framework or domain docs checked
| Result |
| --- | --- | --- | --- |
| Coding-standard prose | Natural Language, Markdown, baseline
inheritance | Documentation Model: Subject-focused content; None (no
framework-specific docs) | Aligned |
| Workflow and issue-process prose | Workflow, contribution workflow, PR
format, commit conventions, Natural Language, Markdown | Documentation
Model and existing stage/source boundaries; None (no framework-specific
docs) | Aligned |
| Capability prose | Natural Language, Markdown, artifact templates |
Affected capability specs and designs; requirements, mechanisms,
examples, and runtime formats preserved | Aligned |
| Home, Vision, Initiatives, and Dictionary introductions | Natural
Language, Markdown | Existing vision, canonical-source, and initiative
boundaries | Aligned |

**Issue convergence.** Searched open issues for subject-focused wording,
self-description, and boilerplate, and checked overlapping documentation
work. #67, #274, #276, #283,
and #286 remain outside this prose cleanup and are not
resolved by it. No additional issue fully converges. Only the scoped
delivery Task is linked for closure.

</details>

<details>
<summary>Related references</summary>

- Resolves #294
- References #293

</details>
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.

Apply code engineering practices to reusable instructions

2 participants