feat(skills): hifi prototype for dt-coach

[mahomedalid]

Pull Request

Description

This pull request introduces a new experimental skill, "hifi-prototype", which provides a structured framework for building and evaluating high-fidelity, local-only prototypes as measurable experiments.

The goal of this contribution is to standardize how prototypes are created, validated, and documented—shifting from ad-hoc prototyping to experiment-driven development with clear success criteria and repeatable workflows.

Key Additions

New Skill: High-Fidelity Prototype Builder

• Added .github/skills/experimental/hifi-prototype/SKILL.md

• Defines:

  • Core philosophy (experiment-first mindset)
  • Design constraints (local-first, measurable outcomes)
  • Step-by-step workflow
  • Validation checklist
  • Troubleshooting guidance

Reference Documentation

• Added references/stack-reference.md

• Includes:

  • Setup commands per stack (HTML/JS, Python, Node.js, .NET)
  • Storage options and tradeoffs
  • Simulation strategies
  • Telemetry and instrumentation guidance

Experiment Templates

• Added references/templates.md

• Provides standardized templates for:

  • Experiment cards
  • Session reports
  • Experiment summaries

Prototyping Workflow

• Added references/workflow.md

• Defines a 6-step, checkpoint-driven workflow:

  1. Experiment definition
  2. Environment setup
  3. Prototype implementation
  4. Instrumentation
  5. Execution
  6. Evidence-based reporting and next steps

---

Related Issue(s)

N/A

---

Type of Change

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 prompt-builder agent and addressed all feedback
• Copilot instructions (.github/instructions/*.instructions.md)
• Copilot prompt (.github/prompts/*.prompt.md)
• Copilot agent (.github/agents/*.agent.md)
• Copilot skill (.github/skills/*/SKILL.md)

Other:

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

---

Sample Prompts (for AI Artifact Contributions)

Context:
This skill is invoked by a DT Coaching agent during Method 7 (High-Fidelity Prototyping).

User Request:

"Generate a hifi prototype for the control room use case"

Execution Flow:

1. The DT Coaching agent (Method 7) invokes the skill for experiment-driven prototyping.

2. The agent determines whether a hypothesis exists:

   • If not provided, it generates one based on the use case.

3. Example generated hypothesis:

   If a control room shift manager is shown an auto-generated summary of operator logs across all desks (simulated with an LLM), they will be able to identify key system events and anomalies faster than reading raw logs, and will trust the summary enough to use it as a starting point for the Daily System Summary Report.

4. The agent then:

   • Defines success metrics (e.g., time-to-insight, accuracy, trust rating)
   • Applies constraints (local-only, simulated data, no production dependencies)

5. Selects appropriate stack guidance from stack-reference.md.

6. Guides the user through the structured workflow:

   • Setup → Build → Instrument → Execute → Evaluate

7. Generates experiment artifacts using provided templates.

Output Artifacts:

• Experiment Card (Markdown)
• Prototype scaffold (based on selected stack)
• Session Report (Markdown)
• Experiment Summary

Example (Experiment Card excerpt):

## Experiment: Control Room Log Summarization

**Hypothesis:**
If a control room shift manager is shown an auto-generated summary of operator logs across all desks, they will identify key events faster and trust the output for reporting.

**Success Metrics:**
- 30–50% reduction in time to identify key events
- ≥80% perceived accuracy/trust score from user
- Reduced cognitive load vs raw log review

**Constraints:**
- Local-only prototype
- Simulated log data
- LLM-based summarization (no external dependencies required at runtime)

Success Indicators:

• Prototype demonstrates clear comparison between raw logs vs summarized view
• Metrics (time, accuracy, trust) are captured and observable
• User can complete a “Daily System Summary Report” using prototype output
• Results support a clear decision: iterate, pivot, or proceed to next stage
• Prototype runs locally, and the gap to bring this to production is too wide

Examples where DT Coach coaches to avoid using it before Method 7, unless instructed by user:

---

Testing

• Validated all markdown files for structure and clarity
• Reviewed skill behavior using /prompt-analyze
• Ensured templates produce consistent, usable outputs
• Manually walked through the workflow using a sample experiment
• Confirmed cross-stack guidance is actionable and accurate

---

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 /prompt-analyze to review contribution
• Addressed all feedback from prompt-builder review
• Verified contribution follows common standards and type-specific requirements

Required Automated Checks

• Markdown linting: npm run lint:md
• Spell checking: npm run spell-check
• Frontmatter validation: npm run lint:frontmatter
• Skill structure validation: npm run validate:skills
• Link validation: npm run lint:md-links
• PowerShell analysis: npm run lint:ps
• Plugin freshness: npm run plugin:generate
• Docusaurus tests: npm run docs:test

---

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 experimental skill intended to explore a more rigorous, experiment-first approach to prototyping. Feedback is especially valuable around:

• Workflow usability
• Template completeness
• Cross-stack consistency
• Real-world applicability in engineering teams

Future iterations may expand into automation or tighter integration with agents.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 87.65%. Comparing base (f7f43d3) to head (f0a9b8d).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1340      +/-   ##
==========================================
- Coverage   87.66%   87.65%   -0.02%     
==========================================
  Files          61       61              
  Lines        9328     9328              
==========================================
- Hits         8177     8176       -1     
- Misses       1151     1152       +1     

Flag	Coverage Δ
pester	85.22% <ø> (-0.02%)	⬇️

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

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[raymond-nassar]

⚠️ Philosophy Alignment Tension with Existing Method 7 Instructions

Great contribution — the experiment-first mindset is compelling. One concern about how this skill aligns with the existing Method 7 framework.

The existing dt-method-07-hifi-prototypes.instructions.md defines hi-fi prototypes as "working system with real data integration, not simulated interactions." The fidelity gradient in dt-method-07-deep.instructions.md lays out five stages:

Stage	Description	Advance When…
1	Paper/cardboard (Method 6 output)	Hypothesis requires interactive behavior
2	Static digital mockup	Users need interaction for meaningful feedback
3	Interactive simulation with simulated data	Simulated data masks behaviors the hypothesis depends on
4	Functional prototype with real data (target state for Method 7)	Advance to production only in Method 9
5	Production-ready (anti-pattern in Method 7)	Redirect effort to testing prep

This new skill maps squarely to Stage 3 of the existing gradient — it is built around simulation layers with [SIMULATED] badges, a sim/ directory with fixture-based mock data, and stub functions for simulated services. The existing framework explicitly positions Stage 3 as below the target hi-fi fidelity for Method 7 and calls for advancing past it when simulated data masks hypothesis-dependent behaviors.

Naming the skill hifi-prototype while its design aligns with Stage 3 (interactive simulation) rather than Stage 4 (functional prototype with real data) creates a terminology conflict with the established framework.

Questions:

1. Is this skill intended to replace the existing Method 7 guidance, complement it at a specific fidelity stage, or serve a distinct use case (e.g., early-stage technical validation before full Method 7)?
2. Should this be renamed or repositioned (e.g., experiment-prototype instead of hifi-prototype) to avoid conflating it with the established hi-fi fidelity definition?

[raymond-nassar]

⚠️ CI/CD Compliance — Required Automated Checks Unchecked

All 8 required automated checks in the PR template are unchecked. Please run the checks and mark them off before merge.

[raymond-nassar]

⚠️ No Linked Work Item or Issue

The PR states "N/A" for related issues. For a new experimental skill introducing 4 files and 495 lines, there should be a tracking issue to establish:

• Feature rationale and acceptance criteria
• Scope approval for the experiment
• Traceability to the product backlog

Without a linked issue, there's no artifact trail connecting this contribution to a planned body of work or a reviewable decision to pursue it.

[raymond-nassar]

⚠️ No Integration Pathway Defined

The PR description states this skill is "invoked by a DT Coaching agent during Method 7 (High-Fidelity Prototyping)", but no agent file, instruction file, or routing mechanism is updated in this PR. The existing DT Coach agent and Method 7 instructions contain no reference to this skill.

Without a defined integration pathway, the skill exists as an orphaned artifact — discoverable only if someone manually browses the skills/experimental/ directory.

Question: Is a follow-up PR planned to wire this skill into the DT Coach agent's Method 7 workflow? If so, can you link or describe that plan?

[raymond-nassar]

💡 Scope Overlap with Existing Method 7 Artifacts

The existing Method 7 instructions already provide:

Existing Artifact	Covers
dt-method-07-hifi-prototypes.instructions.md	3 sub-methods (7a Translation, 7b Construction, 7c Specification), over-engineering prevention, fidelity progression
dt-method-07-deep.instructions.md	Build-vs-simulate decision tree, architecture trade-off analysis, fidelity mapping matrix, technical debt budget

The new skill introduces a parallel 6-step workflow and its own architecture guidance (stack selection, simulation approaches, telemetry implementation) without referencing or deferring to the existing instructions.

This creates a risk of divergent guidance — the DT Coach would have two competing workflow models for Method 7 with no defined precedence. The skill should either reference the existing instructions as the authority (and position itself as the execution tool) or explicitly declare where it diverges and why.

[katriendg]

Can you change the location of the skill and add to the right collections? You can keep your new skill as experimental, regardless of the collection maturity so we can get this out in early mode for feedback.
Thanks.

[katriendg]

As this skill is intended for usage with Design Thinking agents, you want to move the skill into the design-thinking collection. Move the folder name, then add the item under the hve-core-all, and design-thinking.collection.yml files and regenerate plugins.
Set the skill in the design-thinking.collection.yml to maturity: experimental and you will be good to only release it as experimental pre-release version of the extension.