Skip to content

Apply code engineering practices to reusable instructions #292

Closed

Description

Context and request

Contributors need one clear process for correcting durable instructions. Evolutionary Development: The instructions evolve too already requires instruction corrections and shared sources. It does not explicitly apply all code engineering practices to reusable instructions or state the order for correcting a canonical rule before updating dependent instructions.

Clarify that existing section so instruction changes use the same source control, verification, pull request, review, and acceptance practices as code. Immediate self-improvement starts a proposed correction; it does not make an unreviewed change accepted guidance.

Document bodies also need a clear subject boundary. Remove document self-description and maintenance metadata, while retaining navigation fields and the rationale, mechanisms, contract links, and evidence that explain the subject. Apply this boundary through the canonical authoring guidance and reusable templates.

Acceptance criteria

  • The guidance covers durable, reusable standards, guides, stored prompts, skills, and agent files.
  • Instruction changes follow code engineering practices and become accepted guidance through a reviewed, approved, and merged pull request.
  • Missing or incorrect rules are corrected in their owning canonical documents before dependent instructions change. Prompts, skills, and agent instructions reference the source instead of copying its rules.
  • One-off chat requests do not require a source-controlled artifact or a pull request merely to receive or act on the request.
  • Existing headings and anchors remain valid. Each rule has one canonical source, with no copied policy in prompts or skills.
  • Document bodies describe their subject instead of themselves. They omit self-description, bylines, document ownership, approval status, review dates, document versions, revision history, and authoring notes.
  • Required navigation title and description fields remain. Designs retain rationale and mechanisms; subject-specific ownership, versions, observations, and decision evidence remain when needed.
  • Canonical authoring guidance and the reusable templates carry this content boundary so future documentation follows it.

Technical decisions

Keep the lifecycle rule in src\docs\Ways-of-Working\Evolutionary-Development.md. Add the subject-focused content rule to src\docs\Ways-of-Working\Documentation-Model.md, route the authoring conventions in Spec-Driven-Development.md to it, and update the subject-focused placeholders in Spec-Driven-Development-Templates.md. Remove self-introductory wording in these in-scope pages. Keep navigation front matter, useful subject context, design rationale, mechanisms, contract links, and evidence. Do not copy the rule into every document or expand this delivery into a corpus-wide rewrite.

Use the existing documentation checks and focused acceptance examples instead of adding tests that only match prose. Verify the owning document and its instruction routes under the documentation and design evidence gate. This documentation-only change requires no product migration or integration-template change.

This is one independent delivery leaf with no prerequisites or aggregate parent. The Process-PSModule release-alignment task and the instruction trust-boundary work remain out of scope.

Implementation plan

  • Compare the existing section with the requested lifecycle, source-first, and one-off-chat examples before changing it. The reviewed source is f9b335d0b78a3eead0b7efa573936e86cb1e7265.
  • Update the owning section without adding another policy page or changing its heading.
  • Check the resulting guidance against missing PR rules, missing rules in other canonical documents, incorrect instructions, reusable instruction changes, and one-off chat requests.
  • Run shared Markdown lint, local-link validation, cross-repository-link validation, and the required existing Pester suites.
  • Commit the focused documentation change, open a draft PR, and complete the author-side review process. Keep merge and auto-merge disabled for this delivery.

Subject-focused content follow-on

  • Inspect the existing metadata rules and template examples before editing. Confirm that page self-description is present and that navigation fields and subject rationale must remain.
  • Add the general content rule at its owning source and link the authoring conventions to it.
  • Replace self-descriptive template placeholders and the affected pages' self-introductions with subject content.
  • Verify ordinary instructions, design rationale, navigation fields, operational ownership, product versions, observation dates, and decision records against the new boundary.

Activity

  1. MariusStorhaug commented on Nov 12, 2026

    @MariusStorhaug
    MemberAuthor

    Updated only the owning section and checked the five acceptance examples against the diff. The wording applies code engineering practices to reusable instructions, preserves the one-off chat exclusion, and requires reviewed PR acceptance and source-first corrections. Documentation validation is in progress.

  2. MariusStorhaug commented on Nov 12, 2026

    @MariusStorhaug
    MemberAuthor

    Validation passed: shared Markdown lint reported no issues; all local links resolved across 130 documentation files; all 8 cross-repository links resolved; all 66 Pester tests passed across 6 suites. The section heading is unchanged, and the added Contribution Workflow route resolves. The change remains confined to the owning documentation section.

  3. MariusStorhaug commented on Nov 12, 2026

    @MariusStorhaug
    MemberAuthor

    The focused change is committed as a165648 and proposed in #293. All PR checks passed, and the explicit automated review round approved the change with zero new inline comments. Author-side work is complete. The PR remains a draft, with merge and auto-merge disabled. This Task remains open for reviewed merge; the proposed guidance is not yet accepted on main.

  4. MariusStorhaug commented on Nov 12, 2026

    @MariusStorhaug
    MemberAuthor

    The direct user follow-on adds subject-focused authoring to this draft. The user confirmed that navigation title/description fields stay, while self-description and document-maintenance boilerplate leave the body. Updated the acceptance criteria and four-file technical scope before implementation, and reopened validation and author-side review for the next candidate. Designs retain subject rationale and mechanisms; relevant subject data is not treated as document metadata.

  5. MariusStorhaug commented on Nov 12, 2026

    @MariusStorhaug
    MemberAuthor

    Implemented the subject-focused content rule in Documentation Model, routed the authoring conventions and templates to it, and replaced self-descriptive placeholders and introductions in the four in-scope pages. Retained actual navigation front matter, design rationale and mechanisms, subject ownership and versions, observation dates, and decision status. Fresh validation passed: Markdown lint is clean, links resolve across 130 documentation files, all 8 cross-repository links resolve, and all 66 tests pass across 6 Pester suites. The metadata/self-description issue sweep found no additional fully satisfied issue.

  6. MariusStorhaug commented on Nov 12, 2026

    @MariusStorhaug
    MemberAuthor

    The subject-focused follow-on is committed as ff73af3 and included in the existing draft PR. Fresh automated review approved the expanded diff with zero new inline comments. All current validation checks now explicitly report completion and success; Publish is intentionally skipped. A native retry resolved the earlier inconsistent Links state, and the current Links check is 131200062620. Local Markdown/link checks and all 66 Pester tests also passed. All author-side plan steps are complete. The PR stays draft, merge and auto-merge remain disabled, and the Task remains open for reviewed merge.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions