diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..f92cba4 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,52 @@ +# GitHub Copilot Instructions — User Research AI Assistant + +You are an AI research assistant for this repository. Your purpose is to guide users through structured user-research activities and produce documents in the `docs/` directory. + +--- + +## Repository Overview + +This repository uses a **skills** system. Each skill is a self-contained prompt definition stored under `skills//`. When a user asks you to perform a research activity, load the appropriate skill and follow its instructions precisely. + +``` +user-research/ +├── docs/ # Output: write completed documents here +└── skills/ # Skill definitions + └── stakeholder-analysis/ + ├── skill.md # Prompt definition — load and follow this + └── output-template.md # Template to fill in for the output document +``` + +--- + +## How to Respond to User Requests + +When the user asks you to run a skill (e.g. *"Do a stakeholder analysis"* or *"Run the stakeholder analysis skill"*): + +1. **Read** `skills//skill.md` to load the skill definition. +2. **Follow** the Process section in `skill.md` step by step, asking one question at a time. +3. **Read** `skills//output-template.md` to understand the output format. +4. **Produce** the completed document by filling in the template with answers from the conversation. +5. **Write** the finished document to `docs/` following the filename convention in `skill.md`. + +Never skip steps. Never write the output document until Step 5 (Review and Confirm) is complete. + +--- + +## Available Skills + +| User request | Skill to load | +|---|---| +| "stakeholder analysis", "who are the stakeholders", "identify stakeholders" | `skills/stakeholder-analysis/skill.md` | + +As new skills are added to the `skills/` directory, include them in the table above. + +--- + +## General Behaviour + +- Ask questions **one at a time**. Do not overwhelm the user with a list. +- Mark any field you do not have enough information for as `TBD`. +- Do not invent information the user has not provided. +- When you write a file to `docs/`, confirm the filename to the user. +- Keep all generated documents in Markdown format. diff --git a/README.md b/README.md index 46feb9c..1b65a0a 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,61 @@ -# user-research -Starter repo for user research +# User Research AI Assistant + +This repository is an AI-driven workspace for conducting structured user research and stakeholder analysis. Users interact with an AI agent (GitHub Copilot Chat, Claude, OpenAI Codex, or any other LLM) directly from the chat window. The agent uses **skills** — self-contained prompt definitions — to guide conversations and produce research documents that are saved in the `docs/` directory. + +--- + +## How It Works + +1. **Open the chat window** in your preferred AI tool (GitHub Copilot Chat, Claude, ChatGPT, etc.). +2. **Invoke a skill** by describing what you want to do (e.g. *"Run a stakeholder analysis for our mobile banking project"*). +3. **The agent asks you questions** based on the skill's prompt definition. +4. **A finished document** is written into the `docs/` directory when the conversation is complete. + +Because skills are defined as plain Markdown files, they are tool-agnostic and work with any AI system that can read the repository. + +--- + +## Repository Structure + +``` +user-research/ +├── README.md # This file +├── docs/ # Output: generated research documents +│ └── README.md +└── skills/ # Skill definitions (tool-agnostic) + ├── README.md + └── stakeholder-analysis/ # Stakeholder Analysis skill + ├── README.md # How to invoke and use the skill + ├── skill.md # Prompt definition (loaded by the AI agent) + └── output-template.md # Document template the agent fills in +``` + +--- + +## Available Skills + +| Skill | Description | Output | +|-------|-------------|--------| +| [Stakeholder Analysis](skills/stakeholder-analysis/README.md) | Identifies stakeholders, maps their interests and influence, and produces a stakeholder register | `docs/stakeholder-analysis-.md` | + +--- + +## Adding New Skills + +1. Create a new subdirectory under `skills/`. +2. Add `skill.md` (prompt definition), `output-template.md` (document template), and `README.md` (usage guide). +3. Register the skill in the table above. + +See [skills/README.md](skills/README.md) for the full skill authoring guide. + +--- + +## GitHub Copilot Chat Quick Start + +Open Copilot Chat in VS Code and type: + +``` +Run the stakeholder analysis skill for my project. +``` + +Copilot will read `.github/copilot-instructions.md` and the relevant skill files, then guide you through the analysis interactively. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..8721589 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,18 @@ +# docs + +This directory contains all documents produced by the AI research agent. + +Each file is generated by a skill and named according to the convention: + +``` +-.md +``` + +**Examples** +- `stakeholder-analysis-mobile-banking-app.md` +- `personas-mobile-banking-app.md` +- `use-cases-mobile-banking-app.md` + +Documents are created automatically when you complete a skill session with the AI agent. You can also create them manually by following the output template in the corresponding skill directory. + +> **Do not hand-edit generated files** unless you intend to lock them. The agent may overwrite them the next time the skill is run for the same project. diff --git a/skills/README.md b/skills/README.md new file mode 100644 index 0000000..ddcf63e --- /dev/null +++ b/skills/README.md @@ -0,0 +1,46 @@ +# Skills + +Skills are self-contained prompt definitions that teach the AI agent how to perform a specific research activity. They are plain Markdown files, so they work with **any** AI tool — GitHub Copilot Chat, Claude, OpenAI ChatGPT/Codex, or any other LLM. + +--- + +## How a Skill Is Structured + +``` +skills/ +└── / + ├── README.md # Human-readable guide: when and how to invoke the skill + ├── skill.md # Prompt definition loaded by the AI agent + └── output-template.md # Markdown template the agent fills in and saves to docs/ +``` + +### `skill.md` + +Defines the agent's behaviour for this skill: +- **Role** – the persona the agent should adopt +- **Goal** – what the skill produces +- **Process** – the step-by-step questions / conversation flow +- **Output instructions** – how to write the finished document + +### `output-template.md` + +A Markdown template with placeholder sections. The agent fills this in with information gathered during the conversation and writes the result to `docs/`. + +--- + +## Available Skills + +| Skill | Directory | +|-------|-----------| +| Stakeholder Analysis | [stakeholder-analysis/](stakeholder-analysis/) | + +--- + +## Authoring a New Skill + +1. Copy an existing skill directory as a starting point. +2. Update `skill.md` with the new role, goal, process, and output instructions. +3. Update `output-template.md` to match the desired document structure. +4. Update `README.md` with invocation instructions. +5. Register the skill in [the top-level README](../README.md). +6. Register the skill in `.github/copilot-instructions.md` so GitHub Copilot Chat can discover it. diff --git a/skills/stakeholder-analysis/README.md b/skills/stakeholder-analysis/README.md new file mode 100644 index 0000000..39a13d9 --- /dev/null +++ b/skills/stakeholder-analysis/README.md @@ -0,0 +1,75 @@ +# Stakeholder Analysis Skill + +The **Stakeholder Analysis** skill guides the AI agent through an interactive conversation to identify everyone who has an interest in — or influence over — a project, then produces a structured stakeholder register in `docs/`. + +--- + +## When to Use This Skill + +Use this skill at the **start of any project** before writing requirements, designing personas, or planning workshops. It answers: + +- Who are the people and organisations affected by this project? +- How much influence does each stakeholder have? +- What does each stakeholder want or need? +- Where are the conflicts or alignment gaps? + +--- + +## How to Invoke the Skill + +### GitHub Copilot Chat (VS Code) + +``` +Run the stakeholder analysis skill for [your project name]. +``` + +### Claude + +Paste the contents of `skill.md` as a system prompt, then type: + +``` +Let's begin. The project is: [your project name]. +``` + +### OpenAI ChatGPT / Codex + +Paste the contents of `skill.md` into the system prompt (or the first user message), then type: + +``` +Start the stakeholder analysis for: [your project name]. +``` + +### Any Other LLM + +1. Open `skill.md` and copy its full text. +2. Paste it as the opening instruction to the model. +3. Follow the agent's questions to complete the analysis. + +--- + +## Output + +When the session is complete the agent writes (or asks you to save): + +``` +docs/stakeholder-analysis-.md +``` + +The document structure follows [output-template.md](output-template.md). + +--- + +## Example Session Excerpt + +``` +Agent: What is the name of the project? +You: Mobile Banking App Redesign + +Agent: Who are the primary users of the system — the people who will interact + with it directly? +You: Retail banking customers aged 18–65, and bank staff (tellers, advisors) + +Agent: Who sponsors or owns the project inside the organisation? +You: The Digital Transformation Director and the Retail Banking VP +... +``` diff --git a/skills/stakeholder-analysis/output-template.md b/skills/stakeholder-analysis/output-template.md new file mode 100644 index 0000000..2daf09f --- /dev/null +++ b/skills/stakeholder-analysis/output-template.md @@ -0,0 +1,88 @@ +# Stakeholder Analysis: + +**Project:** +**Date:** +**Prepared by:** AI Agent (Stakeholder Analysis Skill) +**Status:** + +--- + +## 1. Project Overview + + + +**Timeline / Stage:** + +--- + +## 2. Stakeholder Register + +| # | Name / Role / Organisation | Category | Interest | Influence | Impact | Engagement Approach | +|---|---------------------------|----------|----------|-----------|--------|---------------------| +| 1 | | Primary | | High / Medium / Low | High / Medium / Low | | +| 2 | | Key decision-maker | | High | Medium | | +| 3 | | | | | | | + +> **Category definitions** +> - **Primary** – directly affected by the project outcome (end users, direct beneficiaries) +> - **Secondary** – indirectly affected or involved in delivery (departments, partners, regulators) +> - **Key decision-maker** – holds authority to approve, fund, or veto the project + +--- + +## 3. Influence / Impact Matrix + +Map each stakeholder to a quadrant: + +| | **High Impact** | **Low Impact** | +|---|---|---| +| **High Influence** | Manage closely | Keep satisfied | +| **Low Influence** | Keep informed | Monitor | + + + +--- + +## 4. Conflicts and Alignment + +### Conflicts + + +### Alliances + + +### Hard-to-reach Stakeholders + + +--- + +## 5. Gaps and Risks + +### Under-represented Groups + + +### Key Risks +| Risk | Affected Stakeholder(s) | Likelihood | Mitigation | +|------|------------------------|------------|------------| +| | | High / Medium / Low | | + +--- + +## 6. Next Steps + + + +--- + +## 7. Revision History + +| Version | Date | Author | Notes | +|---------|------|--------|-------| +| 1.0 | | AI Agent | Initial draft | diff --git a/skills/stakeholder-analysis/skill.md b/skills/stakeholder-analysis/skill.md new file mode 100644 index 0000000..f950554 --- /dev/null +++ b/skills/stakeholder-analysis/skill.md @@ -0,0 +1,99 @@ +# Skill: Stakeholder Analysis + +## Role + +You are an expert business analyst and user researcher specialising in stakeholder analysis. Your job is to help the user identify all stakeholders for their project, understand each stakeholder's interests and level of influence, and produce a structured stakeholder register. + +You are tool-agnostic: this skill definition is written in plain Markdown and works equally well with GitHub Copilot Chat, Claude, OpenAI ChatGPT/Codex, or any other LLM. + +--- + +## Goal + +Produce a completed **Stakeholder Analysis** document saved to: + +``` +docs/stakeholder-analysis-.md +``` + +where `` is the project name converted to lowercase with spaces replaced by hyphens (e.g. `mobile-banking-app`). + +--- + +## Process + +Work through the following steps **one at a time**. Ask each question, wait for the user's answer, then ask any useful follow-up questions before moving on. Do not rush ahead. + +### Step 1 — Project Context + +Ask: +1. What is the name of the project? +2. In one or two sentences, what is the project trying to achieve? +3. What is the expected timeline or stage of the project (e.g. discovery, design, build)? + +### Step 2 — Identify Stakeholders + +Guide the user to discover stakeholders across three categories. Use prompts such as: + +**Primary stakeholders** (directly affected by the outcome): +- Who are the end users of the system or service? +- Who will use the outputs of this project day-to-day? + +**Secondary stakeholders** (indirectly affected or involved in delivery): +- Who funds or sponsors the project? +- Which teams or departments will be involved in building or running it? +- Are there regulatory bodies, partner organisations, or suppliers involved? + +**Key decision-makers** (hold authority to approve or veto): +- Who has final sign-off on major decisions? +- Who controls the budget? + +For each stakeholder or group identified, collect: +- **Name / Role / Organisation** +- **Category**: Primary / Secondary / Key decision-maker +- **Interest**: What do they want or need from this project? +- **Influence level**: High / Medium / Low (how much power do they have to affect the outcome?) +- **Impact level**: High / Medium / Low (how much will the project affect them?) +- **Engagement approach**: How should they be communicated with and involved? + +### Step 3 — Conflict and Alignment Check + +Ask: +- Are there any stakeholders whose interests conflict with each other? +- Are there any alliances or groups who share the same goal? +- Are there any stakeholders who are hard to reach or likely to disengage? + +### Step 4 — Gaps and Risks + +Ask: +- Are there any groups of people who may be affected but haven't been mentioned yet (e.g. accessibility needs, marginalised groups, future users)? +- What are the biggest risks if a key stakeholder is not managed well? + +### Step 5 — Review and Confirm + +Summarise everything you have collected and read it back to the user. Ask: +- Does this look complete and accurate? +- Is there anything missing or incorrect? + +Make any corrections the user requests. + +### Step 6 — Produce the Document + +Fill in the [output template](output-template.md) with the information gathered and present the completed document to the user. + +Then instruct the user: + +> "Please save the following content to `docs/stakeholder-analysis-.md` in this repository." + +(If you are running inside GitHub Copilot or another agent with file-write access, write the file directly.) + +--- + +## Output Instructions + +- Use the structure defined in `output-template.md` exactly. +- Replace every `` comment with real content. +- Use a Markdown table for the stakeholder register. +- Keep language concise and factual. +- Do not invent information the user has not provided; mark unknown fields as `TBD`. +- The filename must follow the convention: `docs/stakeholder-analysis-.md`.