feat(skills): add outcome hypothesis authoring

[Max Zeier (zeier)]

Pull Request

Description

Adds a user-invocable outcome-hypothesis skill for creating and assessing evidence-grounded, falsifiable predictions of measurable business outcomes.

The skill scores D1-D7 readiness before drafting, routes requests to Ready, Provisional, or Investigate, validates outputs against OH.0-OH.12, and makes missing evidence explicit rather than inventing baselines, targets, owners, sources, stakeholders, or dates. It complements Design Thinking's user-centric perspective by articulating measurable business outcomes and enabling continuous optimization toward them.

The capability is registered in the project-planning and hve-core-all packages with generated reference, plugin, and extension projections.

Related Issue(s)

Closes #2679

Type of Change

Select all that apply:

Code & Documentation:

• Bug fix (non-breaking change fixing an issue)
• New feature (non-breaking change adding functionality)
• Breaking change (fix or feature causing existing functionality to change)
• Documentation update

Infrastructure & Configuration:

• GitHub Actions workflow
• Linting configuration (markdown, PowerShell, etc.)
• Security configuration
• DevContainer configuration
• Dependency update

AI Artifacts:

• Reviewed contribution with hve-builder and addressed all actionable findings
• Copilot instructions (.github/instructions/*.instructions.md)
• Copilot prompt (.github/prompts/*.prompt.md)
• Copilot agent (.github/agents/*.agent.md)
• Copilot skill (.github/skills/*/SKILL.md)
• Copilot hook (.github/hooks/*/*.json)
• Eval spec added/updated for changed AI artifacts (evals/)

Note for AI Artifact Contributors:

• Agents: Research, indexing/referencing other project (using standard VS Code GitHub Copilot/MCP tools), planning, and general implementation agents likely already exist. Review .github/agents/ before creating new ones.
• Skills: Must include both bash and PowerShell scripts. See Skills.
• Model Versions: Contributions MUST target models listed in the model catalog (scripts/linting/model-catalog.json) whose provider appears in providerAllowlist and whose status is ga or preview. Run npm run lint:models to validate references.
• See Agents Not Accepted and Model Version Requirements.

Other:

• Script/automation (.ps1, .sh, .py)
• Other (please describe):

Sample Prompts (for AI Artifact Contributions)

User Request:

Help me frame the measurable business result this initiative should change, for whom, and by when.

Execution Flow:

1. Gather and source available evidence.
2. Score D1-D7 readiness and show the scorecard.
3. Route to a Full, Provisional, or Investigate response.
4. Validate Ready and Provisional drafts against OH.0-OH.12.
5. Present the complete result before offering persistence.

Output Artifacts:

The skill returns an inline outcome-hypothesis document with the readiness decision, expected outcomes, indicator table, outcome chain, measurement plan, assumptions, falsification criteria, validation result, and evidence gaps. It writes a Markdown file only after the user confirms a destination.

Success Indicators:

The user can see why the hypothesis is Ready, Provisional, or Investigate; every target is measurable and time-bound; leading and lagging indicators connect to the intervention and business outcome; unknown facts remain explicit gaps.

For detailed contribution requirements, see:

• Common Standards: docs/contributing/ai-artifacts-common.md - Shared standards for XML blocks, markdown quality, RFC 2119, validation, and testing
• Agents: docs/contributing/custom-agents.md - Agent configurations with tools and behavior patterns
• Prompts: docs/contributing/prompts.md - Workflow-specific guidance with template variables
• Instructions: docs/contributing/instructions.md - Technology-specific standards with glob patterns
• Skills: docs/contributing/skills.md - Task execution utilities with cross-platform scripts

Testing

• Fresh HVE Builder contribution review passed after all actionable findings were closed. Reviewed surfaces: canonical skill package, marketplace registration, generated-documentation boundary, and committed eval specification.
• Fresh contained behavior gate passed 12/12 scenarios with zero findings at Medium / GPT-5.6 Terra simulation fidelity. Native activation, retrieval, dispatch, conversion, and persistence reliability were not exercised by this simulation.
• Three advisory behavior-conformance stimuli are committed in evals/behavior-conformance/skill-behavior.eval.yaml: knowledge, indirect tool trigger, and bleed detection. All four static eval gates passed; hosted model-backed execution remains CI-owned.
• Description discovery evaluation passed six positive routes and four negative controls.
• npm run validate:docs passed 10 suites and 101 tests. npm run spell-check passed across 808 files.
• Skill structure, marketplace closure, plugin evidence, generated-document drift, frontmatter, JSON, asset documentation, Markdown, tables, Python lint, static eval gates, targeted links, extension preparation, and git diff --check passed.
• npm run lint:md-links, and therefore npm run validate:local, remain unchecked because five external-link failures reproduce unchanged on upstream/main. The affected upstream files are .github/instructions/rai-planning/rai-license-posture.instructions.md, .github/skills/experimental/powerpoint/SKILL.md, .github/skills/experimental/video-to-gif/SECURITY.md, .github/skills/rai/rai-standards/references/eu-ai-act.md, and .github/skills/rai/rai-standards/SKILL.md. All outcome-hypothesis links pass targeted validation.

Checklist

Required Checks

• Documentation is updated (if applicable)
• Files follow existing naming conventions
• Changes are backwards compatible (if applicable)
• Tests added for new functionality (if applicable)

AI Artifact Contributions

• Used hve-builder review mode to review contribution
• Addressed all actionable findings from the hve-builder review
• Verified contribution follows common standards and type-specific requirements

Required Local Checks

The following local-safe validation commands must pass before merging:

• Local validation aggregate: npm run validate:local
• Documentation validation (if docs changed): npm run validate:docs
• Spell checking: npm run spell-check
• Link validation: npm run lint:md-links

Security Considerations

• This PR does not contain any sensitive or NDA information
• Any new dependencies have been reviewed for security issues
• Security-related scripts follow the principle of least privilege

Additional Notes

This is an additive, documentation-only skill with no executable scripts, hooks, dependencies, workflow changes, lint configuration, security configuration, or devcontainer changes. Accordingly, the 15 unrelated category and security checkboxes remain unchecked as not applicable rather than being marked complete.

The skill is intentionally positioned before BRD/PRD authoring: it establishes the measurable outcome and evidence gaps that later requirements work can formalize. It requires no bash or PowerShell scripts because it has no executable runtime.

[Codecov Comments Bot (codecov-commenter)]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 82.91%. Comparing base (5b2119e) to head (b037e72).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2680      +/-   ##
==========================================
- Coverage   83.17%   82.91%   -0.26%     
==========================================
  Files         180      181       +1     
  Lines       32201    32550     +349     
  Branches       25       25              
==========================================
+ Hits        26782    26989     +207     
- Misses       5416     5558     +142     
  Partials        3        3              

Flag	Coverage Δ
docusaurus	89.92% <ø> (ø)
pester	83.30% <ø> (-0.91%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.
see 5 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Bill Berry (WilliamBerryiii)]

Thanks for this, Max Zeier (@zeier) — we really like this PR and would like to see it land.

The D1-D7 scorecard does something we do not do anywhere else: it makes a team prove they have the evidence before it lets them write a number down. The Investigate route is what gives that teeth. Two other things we noticed: the fabrication guardrails are stated three times independently, which is the right redundancy for a rule a model will otherwise soften; and the eval header count is a fix, not a regression — main declared 133 while actually holding 141.

We have left line comments on the individual files. Each carries a research prompt rather than a prescribed fix, so the plan and implementation stay yours. None are blockers. A fresh hve-builder review afterwards would be worth it, since several comments touch SKILL.md, the reference, and the template together.

Forewarning, not a request: we expect to give this skill a footing in the delivery lifecycle by wiring it into the handoff out of Design Thinking Method 4, augmenting that method with a little extra data-collection coaching. That work is ours to do as maintainers after this merges — nothing in this PR needs to change for it. The skill stays independently useful either way; direct /outcome-hypothesis invocation remains a first-class entry point.

One logistical note: Katrien De Graeve (@katriendg)'s #2682 touches nine of the same files, and two conflicts will auto-merge to the wrong value — you both shift the same three generated sidebar_position values by +1 when the second merge needs +2, and you both rewrite the eval suite header count. Re-running npm run docs:generate after whichever lands second sorts it out. Worth a rebase too; the branch is BEHIND main.

[Max Zeier (zeier)]

Thanks for this, Max Zeier (Max Zeier (@zeier)) — we really like this PR and would like to see it land.

The D1-D7 scorecard does something we do not do anywhere else: it makes a team prove they have the evidence before it lets them write a number down. The Investigate route is what gives that teeth. Two other things we noticed: the fabrication guardrails are stated three times independently, which is the right redundancy for a rule a model will otherwise soften; and the eval header count is a fix, not a regression — main declared 133 while actually holding 141.

We have left line comments on the individual files. Each carries a research prompt rather than a prescribed fix, so the plan and implementation stay yours. None are blockers. A fresh hve-builder review afterwards would be worth it, since several comments touch SKILL.md, the reference, and the template together.

Forewarning, not a request: we expect to give this skill a footing in the delivery lifecycle by wiring it into the handoff out of Design Thinking Method 4, augmenting that method with a little extra data-collection coaching. That work is ours to do as maintainers after this merges — nothing in this PR needs to change for it. The skill stays independently useful either way; direct /outcome-hypothesis invocation remains a first-class entry point.

One logistical note: Katrien De Graeve (Katrien De Graeve (@katriendg))'s #2682 touches nine of the same files, and two conflicts will auto-merge to the wrong value — you both shift the same three generated sidebar_position values by +1 when the second merge needs +2, and you both rewrite the eval suite header count. Re-running npm run docs:generate after whichever lands second sorts it out. Worth a rebase too; the branch is BEHIND main.

Thank you for the thorough and constructive review Bill Berry (@WilliamBerryiii), much appreciated!

All review findings have been addressed through coordinated updates to the Outcome Hypothesis workflow, validation rules, templates, BRD handoff contract, and behavior-conformance coverage. Each review thread includes a reply describing its resolution. The threads remain unresolved, please verify the changes and resolve them when satisfied.

Validation completed:

• Independent multi-model review and targeted static closure
• Fresh HVE Builder behavior review: 16 scenarios, zero findings
• Skill structure, YAML, marketplace, and generated-documentation validation
• Markdown, table, spelling, and repository-wide link checks
• Merge-conflict reconciliation with latest main, preserving all 194 behavior stimuli
• Post-merge targeted validation and generated-documentation drift check

[Katrien De Graeve (katriendg)]

Approving though left a few comments. And because of plugin refactor, please review the Skill contributing guide to automate inclusion and generation of the right files and solve merge conflicts, see https://github.com/microsoft/hve-core/blob/main/docs/contributing/skills.md#plugin-manifest-registration

We would like this to land before #2682. Both PRs extend requirements-author, and this one is the upstream half of the lifecycle, so taking it first keeps the incoming-contract change and the outgoing-contract change in a sensible order. #2682 will pick up the reconciliation. I'll work on that integration once this one lands on main.

[Max Zeier (zeier)]

Approving though left a few comments. And because of plugin refactor, please review the Skill contributing guide to automate inclusion and generation of the right files and solve merge conflicts, see https://github.com/microsoft/hve-core/blob/main/docs/contributing/skills.md#plugin-manifest-registration

We would like this to land before #2682. Both PRs extend requirements-author, and this one is the upstream half of the lifecycle, so taking it first keeps the incoming-contract change and the outgoing-contract change in a sensible order. #2682 will pick up the reconciliation. I'll work on that integration once this one lands on main.

Addressed by adopting the aggregate .github/plugin.json registration model from current main. The Outcome Hypothesis skill is registered there, obsolete package-specific plugin output was reconciled, and generated plugin/reference documentation was refreshed. Plugin and generated-document validation pass.

[Katrien De Graeve (katriendg)]

Thank you for the additional changes, I believe all looks good and I will land my PR in follow-up.

Re-approving so you can merge. Thanks again!

[Max Zeier (zeier)]

Katrien De Graeve (@katriendg), thank you again for the review and approval. I don't have merge permissions, could you please merge the PR for me?

[Katrien De Graeve (katriendg)]

Thank you, reapproving and merging!