feat: add core structure and stakeholder analysis skill

.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/<skill-name>/`. 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-name>/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/<skill-name>/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.

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-<project>.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.

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:
+
+```
+<skill-name>-<project-slug>.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.

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/
+└── <skill-name>/
+    ├── 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.

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-<project-slug>.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
+...
+```

skills/stakeholder-analysis/output-template.md

@@ -0,0 +1,88 @@
+# Stakeholder Analysis: <!-- Project Name -->
+
+**Project:** <!-- Project Name -->
+**Date:** <!-- YYYY-MM-DD -->
+**Prepared by:** AI Agent (Stakeholder Analysis Skill)
+**Status:** <!-- Draft / Final -->
+
+---
+
+## 1. Project Overview
+
+<!-- One or two sentences describing what the project is trying to achieve. -->
+
+**Timeline / Stage:** <!-- e.g. Discovery, Design, Build, Live -->
+
+---
+
+## 2. Stakeholder Register
+
+| # | Name / Role / Organisation | Category | Interest | Influence | Impact | Engagement Approach |
+|---|---------------------------|----------|----------|-----------|--------|---------------------|
+| 1 | <!-- e.g. Retail Customers --> | Primary | <!-- What they want/need --> | High / Medium / Low | High / Medium / Low | <!-- e.g. User testing, surveys --> |
+| 2 | <!-- e.g. Digital Transformation Director --> | Key decision-maker | <!-- What they want/need --> | High | Medium | <!-- e.g. Monthly steering updates --> |
+| 3 | <!-- Add more rows as needed --> | | | | | |
+
+> **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 |
+
+<!-- List each stakeholder and their quadrant, e.g.:
+- Retail Customers → Keep informed (High Impact / Low Influence)
+- Digital Transformation Director → Manage closely (High Impact / High Influence)
+-->
+
+---
+
+## 4. Conflicts and Alignment
+
+### Conflicts
+<!-- Describe any stakeholders whose interests conflict with each other. -->
+
+### Alliances
+<!-- Describe any stakeholders who share the same goal and can be engaged together. -->
+
+### Hard-to-reach Stakeholders
+<!-- Identify stakeholders who are difficult to engage and propose mitigation. -->
+
+---
+
+## 5. Gaps and Risks
+
+### Under-represented Groups
+<!-- Any affected groups not yet represented in the stakeholder register? -->
+
+### Key Risks
+| Risk | Affected Stakeholder(s) | Likelihood | Mitigation |
+|------|------------------------|------------|------------|
+| <!-- e.g. Key sponsor loses interest --> | <!-- e.g. DT Director --> | High / Medium / Low | <!-- e.g. Regular 1-1 updates --> |
+
+---
+
+## 6. Next Steps
+
+<!-- Recommended actions arising from this analysis, e.g.:
+- Schedule discovery interviews with Primary stakeholders
+- Present project vision to Key decision-makers for sign-off
+- Set up a stakeholder communication plan
+-->
+
+---
+
+## 7. Revision History
+
+| Version | Date | Author | Notes |
+|---------|------|--------|-------|
+| 1.0 | <!-- YYYY-MM-DD --> | AI Agent | Initial draft |