Skip to content

first-workflow.md

Latest commit

 

History

History
263 lines (187 loc) · 8.69 KB

first-workflow.md

File metadata and controls

263 lines (187 loc) · 8.69 KB
Raw
title Your First Full Workflow
description Hands-on tutorial using Research, Plan, Implement phases to create a validation script
sidebar_position 6
author Microsoft
ms.date 2026-07-15
ms.topic tutorial
keywords
getting started
rpi workflow
github copilot
tutorial
powershell script
estimated_reading_time 10

Note

Step 3 of 4 in the Getting Started Journey.

Build a real validation script using the Research → Plan → Implement workflow. You'll create a PowerShell script that checks that every docs subfolder has a README.md file.

Tip

This tutorial uses a PowerShell script as the example task. The RPI methodology works identically with any language. If PowerShell isn't relevant to you, substitute your own small task: a utility function, a configuration validator, a documentation checker. The prompts adapt to whatever you describe.

Prerequisites

  • VS Code with GitHub Copilot Chat extension
  • This repository cloned locally
  • Basic familiarity with GitHub Copilot
  • ~15 minutes to complete

The Task

You'll create:

  • scripts/linting/Test-DocsReadme.ps1 - validation script
  • npm script entry in package.json

Multiple unknowns make RPI a good fit for this task: existing script patterns, PowerShell conventions, npm integration, output format. Research first reduces guesswork.

Important

AI can't tell the difference between investigating and implementing. When you ask for code, it writes code. Patterns that look plausible but break your conventions. RPI's constraint system changes the goal: when AI knows it cannot implement, it stops optimizing for "plausible code" and starts optimizing for "verified truth." Learn more about why RPI works.

Before You Start

Tip

Steps 1 and 2 (Your First Interaction and Your First Research) cover the basics. If you've already completed them or have experience with HVE Core agents, continue below.

The /clear command resets Copilot's context between phases. Each RPI phase can start fresh because the research and planning artifacts carry verified context forward. This tutorial invokes /rpi-research, /rpi-plan, and /rpi-implement separately so you can see each responsibility and artifact.

Note

Understanding why /clear matters (not just that you should use it) helps you recognize when context degradation affects your results. See Context Engineering for the full explanation.

Phase 1: Research

Invoke rpi-research

  1. Open Copilot Chat (Ctrl+Alt+I)
  2. Type /rpi-research to activate the Research phase skill

Your Research Prompt

Copy and paste this prompt:

Research what's needed to create a PowerShell script for this repository that
validates every subfolder under docs/ contains a README.md file.

Consider:
* Existing PowerShell script patterns in scripts/linting/
* PSScriptAnalyzer conventions and settings
* How npm scripts are structured in package.json
* Expected output format (exit codes, messages)

What You'll Get

rpi-research analyzes the codebase and returns findings about:

  • Existing PowerShell scripts and their patterns
  • PSScriptAnalyzer settings and conventions
  • Current npm scripts structure
  • Recommended output format

Key Findings to Note

From the research output, identify:

Finding Example
Script location pattern scripts/linting/*.ps1
Naming convention Verb-Noun.ps1 (e.g., Test-DocsReadme.ps1)
npm script pattern "name": "pwsh scripts/path.ps1"
Exit codes exit 0 = success, exit 1 = failure

Phase 2: Plan

Clear and Invoke rpi-plan

  1. Type /clear in the chat to reset context
  2. Type /rpi-plan to activate the Plan phase skill

Your Planning Prompt

Copy and paste this prompt (include findings from Phase 1):

Create an implementation plan to add a README validation script.

Requirements from research:
* Script location: scripts/linting/Test-DocsReadme.ps1
* Follow PowerShell conventions (Verb-Noun naming, comment-based help)
* Add npm script "check:docs-readme" to package.json
* Exit 0 on success, exit 1 on failure
* Output list of folders missing README.md

Plan Output

rpi-plan creates a structured plan with:

  • File creation steps
  • Implementation details for each file
  • Validation criteria

Your Plan Should Include

  1. Create scripts/linting/Test-DocsReadme.ps1 with:

    • Find all immediate subdirectories of docs/
    • Check each has README.md
    • Print missing folders
    • Exit with appropriate code

  2. Update package.json:

    • Add "check:docs-readme" script

Phase 3: Implement

Clear and Invoke rpi-implement

  1. Type /clear in the chat to reset context
  2. Type /rpi-implement to activate the Implement phase skill

Your Implementation Prompt

Copy and paste this prompt:

Implement this plan to add README validation.

Plan:
1. Create scripts/linting/Test-DocsReadme.ps1
   - Include comment-based help
   - Find all immediate subdirectories of docs/
   - Check each has README.md
   - Print missing folders with clear messaging
   - Exit 0 if all pass, exit 1 if any missing

2. Update package.json
   - Add "check:docs-readme": "pwsh scripts/linting/Test-DocsReadme.ps1"

Watch It Work

rpi-implement will:

  1. Create the PowerShell script with proper structure
  2. Update package.json with the npm script
  3. Show you each file change for approval

Confirm each tool call when prompted.

Verify Your Work

Run the Script

npm run check:docs-readme

Expected Output (Success)

Checking docs subfolders for README.md...
✓ docs/contributing/README.md
✓ docs/getting-started/README.md
✓ docs/rpi/README.md

All docs subfolders have README.md

Test Failure Detection

Temporarily rename a README to see the failure case:

Rename-Item docs/rpi/README.md README.md.bak
npm run check:docs-readme
Rename-Item docs/rpi/README.md.bak README.md

Alternative: Coordinated Lifecycle with RPI Agent

The three-skill workflow above separates research, planning, and implementation with /clear between each phase. This is a useful way to learn RPI because you see each phase produce its own artifact.

For day-to-day work, select RPI Agent or invoke /rpi. Both coordinate the same phase skills and include Review and Follow-up when the task reaches those stages.

To compare the experience, select RPI Agent from the agent picker and try this prompt:

Create a PowerShell script that validates every subfolder under docs/ contains a README.md file. Place it at scripts/linting/Test-DocsReadme.ps1 and add an npm script entry.

RPI Agent coordinates the applicable skills without requiring manual agent switches between phases.

What You Learned

  • Use /clear between phases to prevent context pollution through phase separation.
  • Research reduces unknowns by discovering patterns before coding.
  • The plan gives rpi-implement clear requirements, acting as a specification.
  • Findings and plans bridge phases by carrying context, not chat history.

Troubleshooting

Issue Solution
PowerShell not found Ensure pwsh is installed and in PATH
npm script not found Check package.json was saved
Wrong folders checked Verify script targets docs/* pattern
A phase lacks context Attach or name the preceding durable artifact; see Context Engineering

Next Step

You've completed your first full RPI cycle. The methodology works the same way for any task: research the unknowns, plan the approach, implement from the plan.

Continue your journey through the New Contributor Milestones, where Milestone 3 guides you through your first independent workflow on a task you choose yourself.

🤖 Crafted with precision by ✨Copilot following brilliant human instruction, then carefully refined by our team of discerning human reviewers.