Skip to content

Document a session-end standards and framework alignment pass in Ways of Working #111

Description

Context and request

Implementation sessions currently converge on "CI is green and Copilot found nothing", which is not the same as "this change agrees with our process, the coding standards for the languages it touched, and the framework documentation the repository lives under". Nothing in Ways of Working names a moment where an author reconciles the finished change against those three layers, and nothing tells a reviewer to check that it happened. The result is drift that only surfaces later, repository by repository.

We want one generic, reusable gate — usable by humans and agents, in any repository — that runs once at the end of an implementation session, before a draft pull request is marked ready, and that independent review explicitly verifies.

Acceptance criteria:

  • Ways of Working names the gate in the Build phase of the canonical Workflow, positioned before Ready and auto-merge.
  • The Implement stage owns the canonical procedure: when the pass runs, the three layers in precedence order, the required evidence format, and a stop rule for out-of-scope or systemic findings.
  • The Review stage requires the reviewer to verify that the evidence exists, covers the changed surfaces, and is credible rather than decorative.
  • PR Format carries the evidence block without restating stage logic, and the Definition of Ready for Review makes the gate enforceable from the single ready checklist.
  • Guidance stays generic across repositories and links to canonical standards and framework pages instead of restating them.

Non-goals: no per-commit checklist, no repository-specific or PowerShell-specific rules in shared process docs, and no new standalone page where an existing page already owns the concern.

Technical decisions

  • The pass is defined once in src/docs/Ways-of-Working/Workflow-Stages/Implement.md; every other page links to that anchor. Written once, referenced everywhere.
  • Precedence order is Process → Coding Standards → Framework and domain documentation. Process defines the method, the narrower layers define correctness details, and a framework page never overrides a process rule it does not own.
  • Evidence is a table with one row per changed surface: changed surface, standards checked, framework docs checked, result. A result is Aligned, Fixed in this PR, or Exception with a link.
  • Out-of-scope, systemic, or shape-changing findings are filed as follow-up issues through Define and linked as exceptions, so the pull request does not balloon into a second delivery.
  • The framework layer points at the canonical Frameworks index rather than naming one initiative, keeping the guidance repository-agnostic.
  • Definition-of-Ready-and-Done.md is included because PR-Format.md designates it as the single ready checklist; without a bullet there the gate would be described but not enforced.

Implementation plan

  • Define the pass in Workflow-Stages/Implement.md as a numbered stage step with precedence order, evidence table, and stop rule.
  • Add the named gate to the Build phase in Workflow.md, before Ready and auto-merge.
  • Require reviewer verification of the evidence in Workflow-Stages/Review.md.
  • Add the evidence block to the Technical details section in PR-Format.md, referencing the stage procedure.
  • Add the readiness bullet to Definition-of-Ready-and-Done.md.
  • Validate with pwsh .github/scripts/Test-DocumentationLink.ps1 and markdownlint using .github/linters/.markdown-lint.yml.

Metadata

Metadata

Labels

No labels
No labels

Type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions