[Marius Storhaug (MariusStorhaug)]

Workflow and issue guidance describes capture, planning, delivery, review, and operation in direct en-US prose. Contributors, maintainers, and agents can distinguish strategy, aggregate coordination, delivery work, and completion evidence without metaphor or temporary migration status.

No reader action is required. This documentation-only change does not add policy, implementation, enforcement, tooling, or dependencies.

Changed: Workflow and issue guidance states the continuing process directly

The pages use concrete process descriptions and direct work steps. Epic and PBI guidance retains consumer expectations and native coordination; Task and Bug guidance retains technical decisions and test-first delivery plans. Merge remains distinct from publication, deployment, operation, and template completion.

Exact recognized prompts, commands, examples, native types and relationships, normative force, headings, anchors, and complete readiness and evidence gates retain their meaning. The obsolete Feature migration sentence is replaced with the enduring classification rule, using the closed migration and current native-type configuration as evidence.

Technical details

Immutable scope and delivery record

• Review baseline: 1b0d4893c8fefabe604d04393068a8ff6f848082.
• Final head: 8527fa103940caa38e715daeaa5b678d9e31df5a.
• All 21 assigned Markdown pages were read fully after the criteria were derived. Thirteen pages change; eight require no prose change.
• Five small commits were pushed individually. This draft opened after the first complete Workflow improvement, before the remaining scoped work.
• No contribution, PR-format, governance, model, top-level index, functional code, test, configuration, or dependency file changes. The active Keep documentation tooling tests focused on supported behavior #240 surfaces remain untouched.

The criteria come from the fixed baseline's Documentation Model, Natural Language, Technical Writing Guide, Markdown, Documentation, and applicable standard, orchestration-playbook, and guide templates. Existing artifact roles and sections remain; this is not a template restructure.

The official STEMG overview and FAQ were read. The verified local Issue 9 source, MD5 9c720341c350ed77943b2c73d01c716f, was consulted for terminology, approved meanings, active voice, short sentences, conditional instructions, and procedural/descriptive distinctions. The PDF and extract remain local and are not republished.

Full read and disposition evidence

Paths below are relative to src\docs\Ways-of-Working.

Path	Fully read	Disposition and evidence
Workflow.md	Yes	Changed: concrete process, Capture record, local verification, review, Ship, and Operate prose.
Workflow-Stages\Define.md	Yes	Changed: explicit capture/refinement actions and stage boundaries.
Workflow-Stages\Implement.md	Yes	Changed: delivery responsibilities and alignment-pass wording; existing precedence contract retained.
Workflow-Stages\Review.md	Yes	Changed: direct assessment instructions, en-US behavior spelling, evidence checks, and existing approval/check conditions.
Workflow-Stages\Security-Review.md	Yes	Changed: shorter defensive-review and output descriptions; en-US labeled; all fields and constraints retained.
Workflow-Stages\Maintain-Guidance.md	Yes	Changed: duplicated-process wording, source links, pointer responsibilities, and direct validation steps.
Workflow-Stages\index.md	Yes	No change: existing routing, discovery path, and stage boundaries are direct; generated table preserved.
Issues\index.md	Yes	No change: direct planning entry route and native type/process navigation; generated table preserved.
Issues\Process\Format.md	Yes	No change: canonical title/body, metadata, audit, and formatting contracts remain clear.
Issues\Process\Lifecycle.md	Yes	Changed: unblocked Build entry and explicit operational signal records.
Issues\Process\Planning.md	Yes	Changed: independent child context and outcome-based decomposition wording; all normative consumer/technical boundaries retained.
Issues\Process\Relationships.md	Yes	No change: concrete native containment, dependencies, parallelism, and no-duplicate-field rules.
Issues\Process\index.md	Yes	No change: concise factual process navigation; generated table preserved.
Issues\Types\Epic.md	Yes	Changed: direct Initiative strategy-boundary description; consumer scenarios and closure gates retained.
Issues\Types\PBI.md	Yes	Changed: readiness explicitly coordinates delivery; scenarios, children, and closure gates retained.
Issues\Types\Hierarchy.md	Yes	Changed: enduring Feature classification without obsolete migration status.
Issues\Types\Task.md	Yes	No change: executable technical/test-first plan, repository path, and audited operational contracts remain clear.
Issues\Types\Bug.md	Yes	No change: complete reproduction, regression-first, readiness, and closure evidence remains clear.
Issues\Types\index.md	Yes	No change: concise native-type navigation; generated table preserved.
Goal-Setting.md	Yes	Changed: direct strategy, Objective, Key Result, Initiative, and repository-Epic descriptions.
Definition-of-Ready-and-Done.md	Yes	Changed: direct gate descriptions without weakening any readiness, release, documentation, or post-merge ownership condition.

Concrete before/after acceptance evidence

The repeatable prose checks establish 15 desired results absent at the fixed baseline and all 15 present at the final head. The four observed Workflow defect strings are absent. Manual review compares the complete changed passages and their technical meaning, not only these strings.

Surface	Before	After
Workflow process	This is the heartbeat of the MSX ecosystem. and The loop never stops.	The workflow connects issue capture, planning, delivery, review, and operation. Continuous activities and their signals are described directly.
Capture	so it exists for the world to see and "remember"	The issue gives contributors and agents a persistent record to refine.
Operate	After merge, the system is live.	The delivery team operates the system and responds to signals.
Define	Pain before solution - push back on implementation-framed requests.	Identify the problem before you select a solution. The following sentence challenges requests without a stated problem.
Implement	plan from scratch in the stage boundary	Implement does not build an Epic or PBI, start without a delivery plan, or supply independent review.
Review	tests that exercise behaviour	tests that exercise behavior
Security Review	labelled	labeled, with the exact native title and label syntax retained
Maintain Guidance	bloated agent file	duplicate process instructions, replaced with a thin documentation pointer
Goal Setting	A concrete organization-level bet to move a Key Result	An organization-level effort to improve a Key Result
Readiness	Ready gates starting, not scope and figured out on the fly	Readiness determines when work starts, not its scope.
Issue Planning	to be picked up independently	for independent work, retaining local Why and acceptance criteria
Issue Lifecycle	Feed production signals and learning back into the issue model.	Record operational signals and findings in the issue model.
Epic	organization-level bet under an OKR	An Initiative is an organization-level effort under an OKR.
PBI	A PBI is ready for delivery when:	A PBI is ready to coordinate delivery when:
Hierarchy	Feature remains temporary live metadata while ... retires existing usage.	Feature describes a kind of work, not a planning altitude. Its prohibition as a hierarchy node remains.

The exact before-text and immutable source links are also retained in #257. #90 is closed, and the organization API lists Task, Bug, Epic, and PBI, with no Feature type. Only the obsolete migration link is removed; every other link destination remains unchanged.

Final meaning review removed an unintended per-push frequency from an intermediate draft. The final work step is run relevant local checks. Do not push known failures to CI. It preserves the existing obligation without adding policy.

Validation at the final head

Check	Result
Manual source/meaning review	All 21 owned pages fully read; all changed passages compared against the pinned criteria and technical contracts.
Repeatable prose cases	15 expected baseline failures; 15 final result passes.
Technical invariants	All 21 comparisons pass after LF/CRLF normalization: headings/anchors, fenced examples, exact inline syntax/prompts, MUST/SHOULD/MAY force, link targets except the documented removal, generated blocks, titles, front-matter keys, and quotations.
Markdown	Existing repository configuration; 21 owned files; 0 issues; markdownlint-cli2 0.24.0, without installation.
Relative links and anchors	Existing Test-DocumentationLink.ps1; 130 files scanned; all resolve.
Cross-repository links	Existing Test-CrossRepositoryLink.ps1; 7 links across 134 files; all resolve. An anonymous retry hit the shared 60/hour quota; the authenticated retry passed. Authentication was process-local; no credential or persistent access was created.
Repository tests	Existing Pester 6.0.1 runner; 66 passed in 6 suites; 0 failed, skipped, inconclusive, or not run.
Pinned site build	Read-only existing Zensical 0.0.59 environment; archived final source; existing index generation; zensical build --clean; no issues, 2.29 seconds. Five rendered acceptance cases pass, including both regenerated descriptions.
Git diff and scope	git diff --check passes; exactly 13 owned Markdown files change; working tree clean.
Final-head Docs CI	Lint, Links, Test, and Build pass. Publish is intentionally skipped for the PR event.
Final-head network CI	Cross-repository links pass.
Final-head automated review	Approved review is bound to 8527fa103940caa38e715daeaa5b678d9e31df5a; no inline comments. The bounded three-minute helper elapsed before the review arrived; the completed GitHub receipt confirms the clean final round.

Reproducible site sequence: archive 8527fa103940caa38e715daeaa5b678d9e31df5a into a session-only validation directory, run the archived .github\scripts\Update-DocumentationIndex.ps1, then run & $PinnedPython -B -m zensical build --clean from the archived src directory. The private interpreter's package version is verified as 0.0.59. Source configuration stays unchanged; output remains in session artifacts. The global 0.0.50 installation and the shared validation environment are not modified.

Standards and framework alignment

The shared writing set below is the fixed-baseline Natural Language, Technical Writing Guide, Markdown, Documentation, and Documentation Model guidance, plus the official sources cited above. Applicable standard/playbook/guide roles remain in their existing sections.

Changed surface	Standards checked	Framework docs checked	Result
Workflow.md	Shared writing set; existing staged process	None (no framework-specific docs)	Fixed in this PR
Workflow-Stages\Define.md	Shared writing set; guide/playbook; native planning altitude	None (no framework-specific docs)	Fixed in this PR
Workflow-Stages\Implement.md	Shared writing set; guide/playbook; delivery and evidence gates	None (no framework-specific docs)	Fixed in this PR
Workflow-Stages\Review.md	Shared writing set; guide/playbook; review identity and check gates	None (no framework-specific docs)	Fixed in this PR
Workflow-Stages\Security-Review.md	Shared writing set; guide/playbook; defensive scope and output contract	None (no framework-specific docs)	Fixed in this PR
Workflow-Stages\Maintain-Guidance.md	Shared writing set; guide/playbook; thin-pointer contract	None (no framework-specific docs)	Fixed in this PR
Issues\Process\Lifecycle.md	Shared writing set; native lifecycle and relationship contracts	None (no framework-specific docs)	Fixed in this PR
Issues\Process\Planning.md	Shared writing set; native consumer/technical altitude contract	None (no framework-specific docs)	Fixed in this PR
Issues\Types\Epic.md	Shared writing set; aggregate strategy and acceptance contract	None (no framework-specific docs)	Fixed in this PR
Issues\Types\PBI.md	Shared writing set; aggregate readiness contract	None (no framework-specific docs)	Fixed in this PR
Issues\Types\Hierarchy.md	Shared writing set; verified native classification	None (no framework-specific docs)	Fixed in this PR
Goal-Setting.md	Shared writing set; existing Mission/OKR/Initiative boundary	None (no framework-specific docs)	Fixed in this PR
Definition-of-Ready-and-Done.md	Shared writing set; complete existing readiness/completion gates	None (no framework-specific docs)	Fixed in this PR

Accepted differences and exclusions

Direct imperative work steps remain imperative. Exact recognized prompts, native issue types and relationships, commands, Gherkin and Mermaid examples, technical nouns, normative contracts, quotations, and the Now/Next/Later planning model keep their purpose. The retained quotation You build it, you run it. is not rewritten as authored process prose. Time is the subject of Current OKRs and planning horizons; these are not delivery-status narratives.

No generated INDEX marker table is hand-edited or committed. Existing CI generation, also exercised in the isolated build, updates the shared Ways-of-Working index from the two changed descriptions. No heading, anchor, navigation key, requirement reference, or cross-owned link repair is needed.

The app-managed branch name follows the explicit session naming instruction; the one-Task/one-branch/one-PR boundary remains. The campaign's explicit draft-only instruction stops this delivery before the general workflow's ready/auto-merge handoff. The source pages retain that general policy.

These checks support the manual review. Counts, scans, and automated approval do not establish full STE conformance or prove policy implementation/enforcement. No integration-template change applies to this process-prose-only result. The site route does not invoke Release Management, so no release decision block or release:* label applies.

Scoped issue convergence and remaining questions

The finished-change sweep searched open issue titles for workflow, issue, and the campaign prefix. It found this delivery Task, #96, #154, and the other independently owned campaign parts. The complete bodies of #96 and #154 were read. Neither converges: the former proposes a different issue-planning policy, and the latter requests a new entry-side premise-verification gate. This prose change implements neither. Both stay open; no additional closing keyword is added.

Three pre-existing policy questions remain recorded for separate resolution, not silently reconciled:

• Security Review describes an issue per finding in its introduction but one issue containing finding blocks in Output. Reporting cardinality remains unresolved.
• Security Review lists mutable action tags as findings, while Review recognizes the owned controlled-release major-tag exception. The exception boundary remains unresolved.
• Implement's exact Repo-local linter config wins where it disagrees with a published standard. sentence remains. The Coding Standards index says configuration derives from standards, while Markdown says configuration is authoritative on disagreement. Precedence interpretation remains unresolved as directed by the coordinator.

No implementation or validation blocker remains for the focused prose deliverable. These policy questions and the separate requests above remain outside it. The delivery Task stays open because this PR is not merged.

Delivery boundary: This PR stays DRAFT. It is not merged; auto-merge is off; Agent merge is disabled with merge_pr: false. Human review and integration are not performed by this delivery.

Related references

• Resolves [documentation-writing-alignment] Clarify workflow and issue management guidance #257
• References Migrate live issue metadata to the operational model #90 for the completed native-type migration evidence.
• References Clarify issue format: keep technical decisions and implementation plan in PR artifacts #96 and Verify a delivery issue's premise still holds before implementing it #154 as non-convergent, still-open work.
• References Keep documentation tooling tests focused on supported behavior #240 only as an active code/test ownership exclusion.

[Copilot]

🟢 Approved

No active review issues remain for the documentation changes clarifying workflow stages and issue guidance.

No open issues 🎉

What changed in this PR

This documentation-only PR clarifies the canonical workflow and issue guidance with direct, evergreen en-US prose. It distinguishes integration from operation while preserving planning responsibilities and review gates.

Changes:

• Replaces metaphors and indirect wording with explicit work steps.
• Clarifies stage boundaries, issue planning, and readiness and completion criteria.
• Removes temporary Feature migration wording; no executable code, tests, configuration, or dependencies change.

File	Description
src/​docs/​Ways-of-Working/​Workflow.md	Clarifies the continuing process and separates merge from operation.
src/​docs/​Ways-of-Working/​Workflow-Stages/​Security-Review.md	Simplifies defensive-review purpose and reporting instructions.
src/​docs/​Ways-of-Working/​Workflow-Stages/​Review.md	Clarifies independent assessment, evidence checks, and approval conditions.
src/​docs/​Ways-of-Working/​Workflow-Stages/​Maintain-Guidance.md	Makes authoring, routing, and validation instructions explicit.
src/​docs/​Ways-of-Working/​Workflow-Stages/​Implement.md	Clarifies delivery responsibilities and alignment-pass scope.
src/​docs/​Ways-of-Working/​Workflow-Stages/​Define.md	Simplifies capture, refinement, and planning instructions.
src/​docs/​Ways-of-Working/​Issues/​Types/​PBI.md	Describes readiness as coordination of delivery.
src/​docs/​Ways-of-Working/​Issues/​Types/​Hierarchy.md	Removes temporary Feature migration language.
src/​docs/​Ways-of-Working/​Issues/​Types/​Epic.md	Describes the Initiative strategy boundary directly.
src/​docs/​Ways-of-Working/​Issues/​Process/​Planning.md	Clarifies independent child work and outcome-based scope.
src/​docs/​Ways-of-Working/​Issues/​Process/​Lifecycle.md	Clarifies unblocked execution and operational feedback.
src/​docs/​Ways-of-Working/​Goal-Setting.md	Simplifies strategy, objectives, and delivery relationships.
src/​docs/​Ways-of-Working/​Definition-of-Ready-and-Done.md	States readiness, required-check, and completion gates directly.

_{Review effort: Balanced}

[Copilot]

🟢 Approved

No active review issues block the documentation-only updates to the Ways of Working guidance.

No open issues 🎉

_{Review effort: Balanced}