diff --git a/README.md b/README.md index 760238e8d..fc01e4ec6 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ Unify **engineering teams** around **standardized workflows** and **shared best 🧱 **IDE agnostic** · 🏗️ **Legacy systems** · 🌱 **Token-optimized** · 🇫🇷 **Made in France**

- 9 plugins · 51 skills · 2 agents + 9 plugins · 55 skills · 2 agents

[![Open Source](https://img.shields.io/badge/Open_Source-Yes-yellow?logo=open-source-initiative&logoColor=white)](https://opensource.org/) @@ -277,7 +277,7 @@ Repo init, commits, pull / merge requests, release tags, issues. ### 📋 [aidd-pm](plugins/aidd-pm/README.md) -`10 skills` · stable +`14 skills` · stable Three Amigos refinement, Product Briefs, Epics, User Stories, Tasks, Spikes, Defects, PRD, and specs. diff --git a/plugins/aidd-pm/.claude-plugin/plugin.json b/plugins/aidd-pm/.claude-plugin/plugin.json index 3847d63ed..71c900e69 100644 --- a/plugins/aidd-pm/.claude-plugin/plugin.json +++ b/plugins/aidd-pm/.claude-plugin/plugin.json @@ -2,7 +2,7 @@ "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "aidd-pm", "version": "2.5.0", - "description": "Product backlog artifacts, refinement, Product Briefs, Epics, User Stories, Tasks, Spikes, Defects, requirements, and specs.", + "description": "Product backlog artifacts, refinement, Product Briefs, Epics, User Stories, Tasks, Spikes, Defects, requirements, specs, user interviews, release notes, data-driven decisions, and roadmaps.", "author": { "name": "AI-Driven Dev", "url": "https://github.com/ai-driven-dev" @@ -17,7 +17,11 @@ "./skills/07-epic", "./skills/08-three-amigos", "./skills/09-defect", - "./skills/10-task" + "./skills/10-task", + "./skills/11-interview", + "./skills/12-release-notes", + "./skills/13-data-driven-decision", + "./skills/14-roadmap" ], "keywords": [ "backlog", @@ -31,7 +35,12 @@ "specification", "spikes", "defects", - "tickets" + "tickets", + "user-interviews", + "discovery", + "release-notes", + "data-driven-decisions", + "roadmap" ], "repository": "https://github.com/ai-driven-dev/framework", "homepage": "https://ai-driven.dev", diff --git a/plugins/aidd-pm/CATALOG.md b/plugins/aidd-pm/CATALOG.md index 027f408b7..84b3c6489 100644 --- a/plugins/aidd-pm/CATALOG.md +++ b/plugins/aidd-pm/CATALOG.md @@ -18,6 +18,10 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai - [`skills/08-three-amigos`](#skills08-three-amigos) - [`skills/09-defect`](#skills09-defect) - [`skills/10-task`](#skills10-task) + - [`skills/11-interview`](#skills11-interview) + - [`skills/12-release-notes`](#skills12-release-notes) + - [`skills/13-data-driven-decision`](#skills13-data-driven-decision) + - [`skills/14-roadmap`](#skills14-roadmap) --- @@ -172,3 +176,79 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `references` | [relations.md](skills/10-task/references/relations.md) | - | | `-` | [SKILL.md](skills/10-task/SKILL.md) | `Produces or refines a backlog Task for bounded delivery work without independent user value. Use when the user wants to create, link, order, estimate, transition, or complete one. Not for User Stories, Spikes, Defects, or implementation.` | +#### `skills/11-interview` + +| Group | File | Description | +|-------|------|---| +| `actions` | [01-frame.md](skills/11-interview/actions/01-frame.md) | - | +| `actions` | [02-prepare.md](skills/11-interview/actions/02-prepare.md) | - | +| `actions` | [03-synthesize.md](skills/11-interview/actions/03-synthesize.md) | - | +| `actions` | [04-finalize.md](skills/11-interview/actions/04-finalize.md) | - | +| `assets` | [interview-guide.md](skills/11-interview/assets/interview-guide.md) | - | +| `assets` | [interview-synthesis.md](skills/11-interview/assets/interview-synthesis.md) | - | +| `references` | [handoffs.md](skills/11-interview/references/handoffs.md) | - | +| `references` | [insights.md](skills/11-interview/references/insights.md) | - | +| `references` | [persistence.md](skills/11-interview/references/persistence.md) | - | +| `references` | [questions.md](skills/11-interview/references/questions.md) | - | +| `references` | [verbatims.md](skills/11-interview/references/verbatims.md) | - | +| `-` | [SKILL.md](skills/11-interview/SKILL.md) | `Prepares a user interview guide before a meeting, then restructures its raw transcript into a question by question synthesis with exact verbatims. Use when the user wants to prepare or synthesize an interview or client meeting. Not for product decisions.` | + +#### `skills/12-release-notes` + +| Group | File | Description | +|-------|------|---| +| `actions` | [01-collect.md](skills/12-release-notes/actions/01-collect.md) | - | +| `actions` | [02-draft.md](skills/12-release-notes/actions/02-draft.md) | - | +| `actions` | [03-review.md](skills/12-release-notes/actions/03-review.md) | - | +| `actions` | [04-finalize.md](skills/12-release-notes/actions/04-finalize.md) | - | +| `assets` | [fact-sheet.md](skills/12-release-notes/assets/fact-sheet.md) | - | +| `assets` | [release-notes-template.md](skills/12-release-notes/assets/release-notes-template.md) | - | +| `references` | [audiences.md](skills/12-release-notes/references/audiences.md) | - | +| `references` | [handoffs.md](skills/12-release-notes/references/handoffs.md) | - | +| `references` | [persistence.md](skills/12-release-notes/references/persistence.md) | - | +| `references` | [sources.md](skills/12-release-notes/references/sources.md) | - | +| `references` | [tbd-marker.md](skills/12-release-notes/references/tbd-marker.md) | - | +| `-` | [SKILL.md](skills/12-release-notes/SKILL.md) | `Produces traceable release notes from the tickets and merged changes of a release, with internal and customer variants. Use when the user wants to announce, summarize, or communicate a release. Not for cutting a version tag or writing a changelog entry.` | + +#### `skills/13-data-driven-decision` + +| Group | File | Description | +|-------|------|---| +| `actions` | [01-interview.md](skills/13-data-driven-decision/actions/01-interview.md) | - | +| `actions` | [02-plan.md](skills/13-data-driven-decision/actions/02-plan.md) | - | +| `actions` | [03-collect.md](skills/13-data-driven-decision/actions/03-collect.md) | - | +| `actions` | [04-dashboard.md](skills/13-data-driven-decision/actions/04-dashboard.md) | - | +| `actions` | [05-memo.md](skills/13-data-driven-decision/actions/05-memo.md) | - | +| `assets` | [dashboard.md](skills/13-data-driven-decision/assets/dashboard.md) | - | +| `assets` | [decision-memo.md](skills/13-data-driven-decision/assets/decision-memo.md) | - | +| `assets` | [evidence-ledger.md](skills/13-data-driven-decision/assets/evidence-ledger.md) | - | +| `assets` | [tracking-plan.md](skills/13-data-driven-decision/assets/tracking-plan.md) | - | +| `references` | [confidence.md](skills/13-data-driven-decision/references/confidence.md) | - | +| `references` | [counting.md](skills/13-data-driven-decision/references/counting.md) | - | +| `references` | [handoffs.md](skills/13-data-driven-decision/references/handoffs.md) | - | +| `references` | [interview.md](skills/13-data-driven-decision/references/interview.md) | - | +| `references` | [persistence.md](skills/13-data-driven-decision/references/persistence.md) | - | +| `references` | [sources.md](skills/13-data-driven-decision/references/sources.md) | - | +| `-` | [SKILL.md](skills/13-data-driven-decision/SKILL.md) | `Produces a reproducible evidence dashboard and decision memo from customer signals for a pending product decision. Use when the user wants to decide, prioritize, or settle a debate with data rather than intuition. Not for analytics setup.` | + +#### `skills/14-roadmap` + +| Group | File | Description | +|-------|------|---| +| `actions` | [01-frame.md](skills/14-roadmap/actions/01-frame.md) | - | +| `actions` | [02-collect.md](skills/14-roadmap/actions/02-collect.md) | - | +| `actions` | [03-track.md](skills/14-roadmap/actions/03-track.md) | - | +| `actions` | [04-arrange.md](skills/14-roadmap/actions/04-arrange.md) | - | +| `actions` | [05-render.md](skills/14-roadmap/actions/05-render.md) | - | +| `actions` | [06-finalize.md](skills/14-roadmap/actions/06-finalize.md) | - | +| `assets` | [roadmap-template.md](skills/14-roadmap/assets/roadmap-template.md) | - | +| `assets` | [stakeholder-template.md](skills/14-roadmap/assets/stakeholder-template.md) | - | +| `references` | [audiences.md](skills/14-roadmap/references/audiences.md) | - | +| `references` | [handoffs.md](skills/14-roadmap/references/handoffs.md) | - | +| `references` | [persistence.md](skills/14-roadmap/references/persistence.md) | - | +| `references` | [placement.md](skills/14-roadmap/references/placement.md) | - | +| `references` | [progress.md](skills/14-roadmap/references/progress.md) | - | +| `references` | [sources.md](skills/14-roadmap/references/sources.md) | - | +| `references` | [views.md](skills/14-roadmap/references/views.md) | - | +| `-` | [SKILL.md](skills/14-roadmap/SKILL.md) | `Builds or updates a quarterly product roadmap from Epics, Product Briefs, tickets, and decisions, with team and stakeholder views. Use when the user wants to plan a quarter, present its roadmap, or check it against progress. Not for sprint planning.` | + diff --git a/plugins/aidd-pm/README.md b/plugins/aidd-pm/README.md index 4ecfc6ef7..b06619429 100644 --- a/plugins/aidd-pm/README.md +++ b/plugins/aidd-pm/README.md @@ -8,7 +8,7 @@ Product management plugin for the AI-Driven Development framework. First time? Install with `/plugin install aidd-pm@aidd-framework`, then invoke the artifact skill you need. -Covers backlog artifacts, refinement, lifecycle, Product Briefs, Epics, User Stories, Tasks, Spikes, Defects, requirements, and specs. +Covers backlog artifacts, refinement, lifecycle, Product Briefs, Epics, User Stories, Tasks, Spikes, Defects, requirements, specs, user interviews, release notes, data-driven decisions, and quarterly roadmaps. ## Skills @@ -24,3 +24,7 @@ Covers backlog artifacts, refinement, lifecycle, Product Briefs, Epics, User Sto | [4.8] | [three-amigos](skills/08-three-amigos/SKILL.md) | Assess Epic or Story refinement through product, delivery, and quality lenses. | | [4.9] | [defect](skills/09-defect/SKILL.md) | Record, assess, and verify an observed product mismatch. | | [4.10] | [task](skills/10-task/SKILL.md) | Record and manage bounded functional or technical delivery work. | +| [4.11] | [interview](skills/11-interview/SKILL.md) | Prepare a user interview guide, then restructure the transcript into exact verbatims per question. | +| [4.12] | [release-notes](skills/12-release-notes/SKILL.md) | Produce traceable release notes from a release's tickets and merged changes, internal and customer variants. | +| [4.13] | [data-driven-decision](skills/13-data-driven-decision/SKILL.md) | Build a reproducible evidence dashboard and decision memo from customer signals. | +| [4.14] | [roadmap](skills/14-roadmap/SKILL.md) | Build or update a quarterly roadmap with team and stakeholder views. | diff --git a/plugins/aidd-pm/skills/11-interview/SKILL.md b/plugins/aidd-pm/skills/11-interview/SKILL.md new file mode 100644 index 000000000..89cc54045 --- /dev/null +++ b/plugins/aidd-pm/skills/11-interview/SKILL.md @@ -0,0 +1,42 @@ +--- +name: 11-interview +description: Prepares a user interview guide before a meeting, then restructures its raw transcript into a question by question synthesis with exact verbatims. Use when the user wants to prepare or synthesize an interview or client meeting. Not for product decisions. +argument-hint: meeting | transcript +--- + +# Interview + +```mermaid +flowchart LR + meeting([upcoming meeting]) --> frame + transcript([transcript]) --> frame + frame -->|"before the meeting"| prepare + frame -->|"after the meeting"| synthesize + frame -->|"not an interview"| handoff([capability offered]) + prepare --> finalize + synthesize --> finalize + finalize -->|"revise guide"| prepare + finalize -->|"revise synthesis"| synthesize + finalize -->|"authorized"| done([guide or synthesis]) +``` + +## Actions + +Run the flow above. Read only the next action file. + +| Action | Does | +| ---------- | --------------------------------------------- | +| frame | resolve the route and the meeting context | +| prepare | build an interview guide for one meeting | +| synthesize | restructure one transcript by question asked | +| finalize | revise, anonymize, keep, or persist | + +## Transversal rules + +- Keep conclusions and product decisions with the user. +- Never invent a quote, figure, name, or context field; ask for it or mark it unknown. +- Anonymize personal data in every output once the user asks for it. +- Accept transcripts as pasted text or files from any meeting or dictation tool; depend on none. +- Emit plain Markdown that pastes into a wiki or ticketing tool unchanged. +- Ask natural questions, one at a time; never expose actions, references, or unchanged state. +- Require explicit approval before any write. diff --git a/plugins/aidd-pm/skills/11-interview/actions/01-frame.md b/plugins/aidd-pm/skills/11-interview/actions/01-frame.md new file mode 100644 index 000000000..3b6223f95 --- /dev/null +++ b/plugins/aidd-pm/skills/11-interview/actions/01-frame.md @@ -0,0 +1,32 @@ +# 01 - Frame + +Resolve which moment the user is in and the context the interview serves. + +## Input + +An upcoming meeting, a transcript as pasted text or a file, an existing guide, or the current context. + +## Output + +The route, `prepare` or `synthesize`, and a confirmed context: participants and their roles, interview goal, the decision it feeds, and any existing guide. + +## Process + +1. **Route.** Take `prepare` for a meeting still to come and `synthesize` for a supplied transcript; otherwise ask which and wait. + - Neither an interview nor a client meeting: apply [handoffs](../references/handoffs.md) and stop. +2. **Read.** Read the supplied transcript, guide, and any project artifact the user names before asking anything they already answer. +3. **Collect.** Ask for the missing context field that most changes the output and wait. + - `prepare` needs who is met and their role, why the meeting happens, and the decision it feeds. + - `synthesize` needs who spoke and their role, and the interview goal; the decision it feeds is optional. + - Loop on `Collect` while a needed field is missing. +4. **Confirm.** Restate the context in one short block and wait for correction. + +## Test + +| Case | Pass | +| --- | --- | +| No route inferable | workspace unchanged; exactly one question on before or after the meeting | +| Prepare without a decision | no guide drafted; one question on the decision the meeting feeds | +| Field absent from every input | asked or marked unknown, never filled with an assumed value | +| Transcript supplied | no question asked that the transcript already answers | +| Not an interview | no guide or synthesis; the offered capability returned | diff --git a/plugins/aidd-pm/skills/11-interview/actions/02-prepare.md b/plugins/aidd-pm/skills/11-interview/actions/02-prepare.md new file mode 100644 index 000000000..627229ab5 --- /dev/null +++ b/plugins/aidd-pm/skills/11-interview/actions/02-prepare.md @@ -0,0 +1,32 @@ +# 02 - Prepare + +Build an interview guide for one upcoming meeting. + +## Input + +The confirmed context from frame. + +## Output + +A review-ready interview guide kept in context. + +## Process + +1. **Goal.** State one learning goal tied to the decision the meeting feeds. +2. **Hypotheses.** List the beliefs the meeting can confirm or refute, each with the signal that would refute it. + - The user supplied none: propose candidates from the context, ask which to keep, and wait. +3. **Questions.** Write and order the questions per [questions](../references/questions.md), each hypothesis covered by at least one. +4. **Observe.** List the signals to watch beyond the answers per [questions](../references/questions.md). +5. **Compose.** Fill [the guide template](../assets/interview-guide.md). +6. **Show.** Present the complete draft without persisting it. + +## Test + +| Case | Pass | +| --- | --- | +| Hypothesis | each has a refuting signal and at least one question that can produce it | +| Question | passes every check in `questions`; none names the product or a solution | +| Order | sections follow the sequence in `questions` | +| Context | goal, participants, and decision trace to frame; none invented | +| Cleanup | no placeholder or template instruction remains | +| Handoff | complete draft shown; workspace unchanged | diff --git a/plugins/aidd-pm/skills/11-interview/actions/03-synthesize.md b/plugins/aidd-pm/skills/11-interview/actions/03-synthesize.md new file mode 100644 index 000000000..edccde531 --- /dev/null +++ b/plugins/aidd-pm/skills/11-interview/actions/03-synthesize.md @@ -0,0 +1,37 @@ +# 03 - Synthesize + +Restructure one raw transcript into a synthesis organized by question asked. + +## Input + +The transcript, the confirmed context from frame, and the guide when one exists. + +## Output + +A review-ready synthesis kept in context, with its attribution flags listed. + +## Process + +1. **Segment.** Split the transcript into the questions actually asked, in the order asked. + - A guide exists: map each asked question to its guide question and list the guide questions never asked. + - A topic raised without a question goes under `Unprompted`. +2. **Attribute.** Assign each turn a speaker per [verbatims](../references/verbatims.md), flagging every uncertain one. +3. **Quote.** Select the verbatims under each question per [verbatims](../references/verbatims.md). +4. **Derive.** Derive pains, needs, and open questions per [insights](../references/insights.md). +5. **Tag.** Tag each insight with a theme per [insights](../references/insights.md), unless the user declined themes. +6. **Verify.** Search the transcript for every verbatim and fix or drop any that is not an exact match. +7. **Compose.** Fill [the synthesis template](../assets/interview-synthesis.md). +8. **Show.** Present the complete draft without persisting it. + +## Test + +| Case | Pass | +| --- | --- | +| Verbatim | found character for character in the transcript, bar the marks `verbatims` allows | +| Unclear speaker | quote carries a flag listed under attribution flags; no speaker guessed | +| Interviewer speech | never quoted as a verbatim | +| Insight | cites at least one verbatim id | +| Figure or name | present in the transcript or context; none invented | +| Guide present | every guide question appears, answered or listed as not asked | +| Themes declined | no theme column or tag emitted | +| Handoff | complete draft shown; workspace unchanged | diff --git a/plugins/aidd-pm/skills/11-interview/actions/04-finalize.md b/plugins/aidd-pm/skills/11-interview/actions/04-finalize.md new file mode 100644 index 000000000..b1a74b75a --- /dev/null +++ b/plugins/aidd-pm/skills/11-interview/actions/04-finalize.md @@ -0,0 +1,33 @@ +# 04 - Finalize + +Let the user revise, anonymize, keep, or persist the guide or synthesis. + +## Input + +The draft, its sources, and the user's feedback. + +## Output + +The authorized guide or synthesis, in session or at its resolved path. After writing, report the path and the verification result. Without a write, state that no persisted change occurred. + +## Process + +1. **Review.** Invite corrections and wait. + - A content correction: return to `prepare` or `synthesize`. +2. **Anonymize.** When the user asked for it, apply the anonymization in [verbatims](../references/verbatims.md). +3. **Authorize.** Ask whether to keep the draft in session or persist it, and wait. +4. **Place.** Apply [persistence](../references/persistence.md) to resolve the file. +5. **Write.** Persist only the authorized file; preserve user edits in an existing one. +6. **Verify.** Read the written file back and check every verbatim still matches the transcript, bar anonymization marks. +7. **Continue.** Apply [handoffs](../references/handoffs.md) to the next move. + +## Test + +| Case | Pass | +| --- | --- | +| Unauthorized draft | workspace unchanged; response ends with one session-or-persist question | +| Anonymized | no personal identifier from the transcript remains; each one replaced by the same label everywhere | +| Persisted | one file at the standard path; its read-back matches the approved draft | +| Existing file | edits outside the authorized change preserved | +| Handoff | capability offered with what was observed, never invoked | +| No write | response states that no persisted change occurred | diff --git a/plugins/aidd-pm/skills/11-interview/assets/interview-guide.md b/plugins/aidd-pm/skills/11-interview/assets/interview-guide.md new file mode 100644 index 000000000..6e14abe79 --- /dev/null +++ b/plugins/aidd-pm/skills/11-interview/assets/interview-guide.md @@ -0,0 +1,59 @@ +--- +type: interview-guide +meeting: "" +status: draft +--- + +# Interview Guide: + + + +## Goal + + + +## Hypotheses + +| Id | Hypothesis | Refuted if | Questions | +| --- | --- | --- | --- | +| H1 | | | | + +## Questions + +### Opening + +1. + +### Context + +1. + +### Last time + +1. + +### Pains and workarounds + +1. + +### Hypothesis probes + +1. + +### Wrap-up + +1. + +## Follow-ups + +- + +## What to observe + +- + +## Logistics + + + +> Fill every `<...>`, drop `Logistics` when nothing is known, and delete this line. Nothing of this scaffold survives in the guide. diff --git a/plugins/aidd-pm/skills/11-interview/assets/interview-synthesis.md b/plugins/aidd-pm/skills/11-interview/assets/interview-synthesis.md new file mode 100644 index 000000000..00d36e9dd --- /dev/null +++ b/plugins/aidd-pm/skills/11-interview/assets/interview-synthesis.md @@ -0,0 +1,65 @@ +--- +type: interview-synthesis +meeting: "" +status: draft +--- + +# Interview Synthesis: + +| Field | Value | +| --- | --- | +| Participants | | +| Interviewers | | +| Goal | | +| Decision it feeds | | +| Source | | + +## Key Points + +- () + +## Q1. + +**Verbatims** + +> **V1.1** "" () + +**Pains and needs** + +- : () + +**Open questions** + +- + +## Unprompted + +> **V0.1** "" () + +## Not Asked + +- + +## Hypotheses Signal + +| Id | Hypothesis | Signal | Evidence | +| --- | --- | --- | --- | +| H1 | | | | + +## Insight Table + +| Id | Kind | Theme | Statement | Evidence | Speaker role | +| --- | --- | --- | --- | --- | --- | +| I1 | | | | | | + +## Interpretations + +- : + +## Attribution Flags + +| Verbatim | Flag | Why | +| --- | --- | --- | +| | | | + +> Repeat the `Q` block per question asked. Drop `Unprompted`, `Not Asked`, `Hypotheses Signal`, `Interpretations`, or `Attribution Flags` when empty, and the `Theme` column when themes were declined. Fill every `<...>` and delete this line. Nothing of this scaffold survives in the synthesis. diff --git a/plugins/aidd-pm/skills/11-interview/references/handoffs.md b/plugins/aidd-pm/skills/11-interview/references/handoffs.md new file mode 100644 index 000000000..c710b3ca6 --- /dev/null +++ b/plugins/aidd-pm/skills/11-interview/references/handoffs.md @@ -0,0 +1,11 @@ +# Handoffs + +Offer the named capability with what was observed, then stop. Never invoke it silently, never write outside a guide or synthesis. + +| Observed | Capability | Return | +| --- | --- | --- | +| evidence for a product opportunity | Product Brief | one-way; the synthesis is its interview evidence | +| themed insights across several interviews | a data-driven decision capability | one-way; the insight table is its input | +| a user describing an observed product mismatch | Defect | one-way | +| a need bounded enough for one deliverable behavior | User Story | one-way | +| no match | none | report what was observed | diff --git a/plugins/aidd-pm/skills/11-interview/references/insights.md b/plugins/aidd-pm/skills/11-interview/references/insights.md new file mode 100644 index 000000000..6e608b1c5 --- /dev/null +++ b/plugins/aidd-pm/skills/11-interview/references/insights.md @@ -0,0 +1,31 @@ +# Insights + +An insight restates in neutral words what the verbatims show. It is evidence, not a decision. + +## Kinds + +| Kind | Is | Cites | +| --- | --- | --- | +| Pain | a problem the person lived, with its consequence or workaround | at least one verbatim | +| Need | a progress the person seeks, stated or shown | at least one verbatim | +| Open question | what the meeting left unresolved, vague, or contradictory | the verbatim or question that raised it | + +## Rules + +| Rule | Handling | +| --- | --- | +| Interpretation beyond the words | labeled `interpretation`, kept apart from the insight | +| One interview | never a frequency, share, or trend claim | +| Hypothesis from the guide | marked `supports`, `challenges`, or `no signal`, with verbatim ids; never `validated` | +| Figure | only as said in the transcript, with its verbatim id | + +## Themes + +Themes let rows from several interviews be counted together later. + +| Rule | Handling | +| --- | --- | +| Form | kebab-case noun phrase, such as `onboarding-friction` | +| Vocabulary | reuse the user's theme list when one exists; otherwise propose one | +| Count | one theme per insight, a second only when both are needed | +| Row | id, kind, theme, statement, verbatim ids, speaker role | diff --git a/plugins/aidd-pm/skills/11-interview/references/persistence.md b/plugins/aidd-pm/skills/11-interview/references/persistence.md new file mode 100644 index 000000000..6c59c46d8 --- /dev/null +++ b/plugins/aidd-pm/skills/11-interview/references/persistence.md @@ -0,0 +1,18 @@ +# Persistence + +Write one folder per meeting, `aidd_docs/product/interviews/-/`, dated by the meeting. The slug names the topic or the role met, never a person when anonymized. + +| Artifact | File | +| --- | --- | +| Interview guide | `guide.md` | +| Synthesis | `synthesis.md` | +| Raw transcript | `transcript.md`, only when the user asks | + +| Situation | Result | +| --- | --- | +| explicit target given by the user | use it | +| no file for this meeting | create one | +| file exists for this meeting | update it; preserve edits outside the change | +| several candidate meetings | ask the user | + +Markdown is the only support this skill writes. Pasting into a wiki or ticketing tool is the user's move. diff --git a/plugins/aidd-pm/skills/11-interview/references/questions.md b/plugins/aidd-pm/skills/11-interview/references/questions.md new file mode 100644 index 000000000..e66ddc1f2 --- /dev/null +++ b/plugins/aidd-pm/skills/11-interview/references/questions.md @@ -0,0 +1,43 @@ +# Questions + +A good question makes the person tell a past story, never predict, approve, or design. + +## Checks + +| Check | Pass when | Instead of | Ask | +| --- | --- | --- | --- | +| Open | it cannot be answered yes or no | "Do you track this?" | "How do you track this today?" | +| Non-leading | it names no expected answer, product, or solution | "Would a dashboard help?" | "What did you do next?" | +| Past-anchored | it targets a specific past event, not future intent | "Would you use it weekly?" | "When did this last happen?" | +| Single | it asks one thing | "How and why do you do it?" | "How do you do it?" then "Why?" | +| Neutral | it carries no judgment word | "What is frustrating about it?" | "How did that go?" | + +## Sequence + +| Section | Purpose | +| --- | --- | +| Opening | purpose of the meeting, consent to record, no product shown | +| Context | the person's role, routine, and where the topic sits in it | +| Last time | walk through the last concrete occurrence, step by step | +| Pains and workarounds | what went wrong, what they did instead, what it cost | +| Hypothesis probes | questions that can refute each hypothesis | +| Wrap-up | what was missed, who else to talk to, follow-up agreed | + +## Follow-ups + +- "Tell me more about that." +- "Why was that important?" +- "Can you show me?" +- "What happened just before?" +- A silence of a few seconds. + +## What to observe + +| Signal | Tells | +| --- | --- | +| Emotion: a sigh, a laugh, a change of pace | where a pain is real | +| A workaround, file, or tool shown | the need is already paid for | +| Said and done diverge | which claim to trust less | +| A number volunteered | the size of the problem | +| The person's own words for things | the vocabulary to reuse | +| A topic avoided or cut short | a question to revisit | diff --git a/plugins/aidd-pm/skills/11-interview/references/verbatims.md b/plugins/aidd-pm/skills/11-interview/references/verbatims.md new file mode 100644 index 000000000..f69cc7a3a --- /dev/null +++ b/plugins/aidd-pm/skills/11-interview/references/verbatims.md @@ -0,0 +1,44 @@ +# Verbatims + +A verbatim is a copy of what the person said, never a rewrite. + +## Allowed marks + +| Need | Mark | +| --- | --- | +| Cut words inside a quote | `[...]` | +| A gap the transcriber marked | keep its own mark, such as `[inaudible]` | +| Clarify a pronoun or reference | `[bracketed words]` | +| Anonymize | the replacement label in brackets, such as `[Client A]` | +| Translation, when asked | beside the original quote, labeled, never replacing it | + +Nothing else changes inside a quote: no paraphrase, no grammar fix, no merge of two turns, no filler dropped without `[...]`. + +## Selection + +- Quote what carries a fact, a pain, a workaround, a number, or an emotion. +- Keep one to three verbatims per question; prefer the most concrete. +- Never quote the interviewer as evidence. +- Give each verbatim an id `V.`, such as `V2.1`, and `V0.` under `Unprompted`. + +## Attribution + +Transcription and dictation tools often mislabel or swap speakers. + +| Situation | Label | Flag | +| --- | --- | --- | +| Speaker named and consistent with the context | name or role | none | +| Generic label such as `Speaker 1` | `speaker unclear` | candidates and the clue for each | +| Name contradicts the context or the content | the transcript label | `attribution conflict`, with the contradiction | +| Two voices merged in one turn | `speaker unclear` | `merged turn` | + +Never resolve a flag by guessing; the user resolves it. + +## Anonymization + +| Data | Replace with | +| --- | --- | +| Person's name | a role label, numbered consistently, such as `[User A]` | +| Company or client | `[Company]` or a sector label | +| Email, phone, address, or account id | `[redacted]` | +| Any other identifier the user names | the label the user chooses | diff --git a/plugins/aidd-pm/skills/12-release-notes/SKILL.md b/plugins/aidd-pm/skills/12-release-notes/SKILL.md new file mode 100644 index 000000000..53a53b843 --- /dev/null +++ b/plugins/aidd-pm/skills/12-release-notes/SKILL.md @@ -0,0 +1,38 @@ +--- +name: 12-release-notes +description: Produces traceable release notes from the tickets and merged changes of a release, with internal and customer variants. Use when the user wants to announce, summarize, or communicate a release. Not for cutting a version tag or writing a changelog entry. +argument-hint: release | range | tickets +--- + +# Release Notes + +```mermaid +flowchart LR + source([release, ref range, or ticket list]) --> collect --> draft --> review --> finalize + collect -->|"nothing resolvable"| ask([one question]) + collect -->|"handoff"| offer([capability offered]) + review -->|"revise"| draft + finalize -->|"approved"| done([saved release notes]) + finalize -->|"not approved"| session([notes kept in session]) +``` + +## Actions + +Run the flow above. Read only the next action file. + +| Action | Does | +| -------- | ----------------------------------------------- | +| collect | gather the release facts into one fact sheet | +| draft | write the notes for each audience from the facts | +| review | challenge every claim and what goes public | +| finalize | save the approved notes | + +## Transversal rules + +- Never invent a feature, metric, date, or user; mark every gap instead. +- Every item in the notes traces to a ticket, pull request, or commit. +- Derive every audience variant from the same fact sheet. +- Read the repository and the ticketing tool; never write to either. +- Keep wording and publication decisions with the user. +- Require explicit approval before any write; never share, send, or publish the notes. +- Ask natural questions; never expose actions, references, or unchanged state. diff --git a/plugins/aidd-pm/skills/12-release-notes/actions/01-collect.md b/plugins/aidd-pm/skills/12-release-notes/actions/01-collect.md new file mode 100644 index 000000000..428485e07 --- /dev/null +++ b/plugins/aidd-pm/skills/12-release-notes/actions/01-collect.md @@ -0,0 +1,35 @@ +# 01 - Collect + +Gather what the release shipped into one fact sheet, each row tied to its source. + +## Input + +A release name or version, a ref range, or a ticket list, pasted or as ids. Optional epic, PRD, or roadmap paths. + +## Output + +One fact sheet per [fact-sheet.md](../assets/fact-sheet.md), kept in the session, or one open question when nothing resolves. + +## Process + +1. **Range.** Resolve the release range per [sources.md](../references/sources.md). + - No range and no ticket list resolve: ask one question for the refs or the tickets, then stop. +2. **Changes.** List the merged pull requests, commits, and changed paths of the range per [sources.md](../references/sources.md). +3. **Tickets.** Resolve the ticketing tool and every ticket id per [sources.md](../references/sources.md), then read each ticket's title, type, status, parent, and acceptance criteria. + - The tool is unreachable: ask the user to paste the tickets. +4. **Context.** Read the epic, PRD, product brief, or roadmap that each ticket's parent or the user points to. +5. **Reconcile.** Match tickets to changes and set each row's status per [sources.md](../references/sources.md). +6. **Areas.** Group the changed paths of each row into the product capability they serve, read from the ticket and the code's own naming. +7. **Record.** Fill [fact-sheet.md](../assets/fact-sheet.md) and replace every missing cell per [tbd-marker.md](../references/tbd-marker.md). +8. **Route.** Apply [handoffs.md](../references/handoffs.md) to what the sources revealed. + +## Test + +| Case | Pass | +| --- | --- | +| The action completes | `git status --porcelain` and the ticket records read the same after as before | +| The fact sheet is read back | every row carries a ticket, pull request, or commit in `Source` | +| A listed ticket has no merged change in the range | its row reads `not in this release`, never `shipped` | +| A merged change matches no ticket | it has its own `untracked change` row | +| No range and no ticket list | no fact sheet; one question for the refs or the tickets | +| A cell has no source | it holds a `TBD:` question, not a guess | diff --git a/plugins/aidd-pm/skills/12-release-notes/actions/02-draft.md b/plugins/aidd-pm/skills/12-release-notes/actions/02-draft.md new file mode 100644 index 000000000..9a1206925 --- /dev/null +++ b/plugins/aidd-pm/skills/12-release-notes/actions/02-draft.md @@ -0,0 +1,34 @@ +# 02 - Draft + +Write the release notes for each requested audience from the fact sheet. + +## Input + +The fact sheet from collect, the requested audiences, and any review findings to fold. + +## Output + +One release notes draft per audience, per [release-notes-template.md](../assets/release-notes-template.md). + +## Process + +1. **Audience.** Take the audiences the user named; otherwise ask whether the notes are internal, customer-facing, or both. +2. **Fill.** Fill [release-notes-template.md](../assets/release-notes-template.md) for the internal audience from the fact sheet rows. + - `What you can do now` restates each shipped row's user outcome in plain words. + - `Impacted areas` summarizes each functional area, never a file list. + - `Known limitations` takes the fact sheet's limitations and every partially shipped row. +3. **Demo.** Write the demo steps from the acceptance criteria of shipped rows only. + - No shipped row carries acceptance criteria: write one TBD marker instead of steps. +4. **Derive.** Derive each other audience from the internal draft per [audiences.md](../references/audiences.md), line by line. +5. **Gaps.** Collect every TBD marker per [tbd-marker.md](../references/tbd-marker.md) into `Open questions`. +6. **Show.** Present every draft, then hand them to review. + +## Test + +| Case | Pass | +| --- | --- | +| An internal draft is read back | every item in `Scope`, `What you can do now`, and `Impacted areas` names a ref present in the fact sheet | +| A customer draft is read back | each line maps to an internal line, and no ticket id, pull request, or file path appears | +| A number, date, or name appears in a draft | the same value appears in the fact sheet | +| A row is `not in this release` | it is absent from `What you can do now` in every draft | +| The draft is shown | every section the audience keeps is present, and no other | diff --git a/plugins/aidd-pm/skills/12-release-notes/actions/03-review.md b/plugins/aidd-pm/skills/12-release-notes/actions/03-review.md new file mode 100644 index 000000000..941d3ae85 --- /dev/null +++ b/plugins/aidd-pm/skills/12-release-notes/actions/03-review.md @@ -0,0 +1,30 @@ +# 03 - Review + +Challenge every claim of the drafts and let the user decide their wording and what goes public. + +## Input + +The drafts from draft and the fact sheet behind them. + +## Output + +The drafts approved by the user, or their corrections sent back to draft. + +## Process + +1. **Trace.** Test each line of each draft against its fact sheet row, and flag any claim stronger than its source. +2. **Expose.** Flag every publication risk the customer draft carries per [audiences.md](../references/audiences.md). +3. **Present.** Show the flags, the open TBD markers, and the drafts together. +4. **Decide.** Ask the user to approve the wording and choose what is public, one open question per unresolved flag. + - Corrections or answered TBD markers: send them back to draft. + - A customer draft still holds a TBD marker: it cannot be approved for sharing. + +## Test + +| Case | Pass | +| --- | --- | +| A line overstates its source | it is flagged with the fact sheet row it contradicts | +| The customer draft names a flagged risk | the risk is shown to the user, and the line is neither kept nor dropped silently | +| The user asks for changes | the drafts return to draft and are shown again | +| A customer draft holds a TBD marker | it is not marked approved | +| The review runs | no file is written | diff --git a/plugins/aidd-pm/skills/12-release-notes/actions/04-finalize.md b/plugins/aidd-pm/skills/12-release-notes/actions/04-finalize.md new file mode 100644 index 000000000..7b5fbe094 --- /dev/null +++ b/plugins/aidd-pm/skills/12-release-notes/actions/04-finalize.md @@ -0,0 +1,28 @@ +# 04 - Finalize + +Save the approved release notes, or keep them in the session. + +## Input + +The approved drafts and the user's write decision. + +## Output + +One saved file per approved audience, with its path and `status: approved`, or a statement that no persisted change occurred. + +## Process + +1. **Resolve.** Select the target of each draft per [persistence.md](../references/persistence.md). +2. **Authorize.** Confirm the user approved the write; otherwise return the drafts in the session. +3. **Write.** Save each approved draft with `status: approved`, preserving any existing file's content outside the approved change. +4. **Verify.** Read each saved file back and report its path and what changed. +5. **Continue.** Apply [handoffs.md](../references/handoffs.md) to anything left open, and remind the user that sharing is their step. + +## Test + +| Case | Pass | +| --- | --- | +| The write is not approved | no file under `aidd_docs/releases/` changes, and the result says so | +| An approved draft is saved | the file exists at the resolved path and reads `status: approved` | +| Notes exist for the same release and audience | the same file is updated; no second file is created | +| The run ends | nothing was sent, shared, or published | diff --git a/plugins/aidd-pm/skills/12-release-notes/assets/fact-sheet.md b/plugins/aidd-pm/skills/12-release-notes/assets/fact-sheet.md new file mode 100644 index 000000000..1f76efbe6 --- /dev/null +++ b/plugins/aidd-pm/skills/12-release-notes/assets/fact-sheet.md @@ -0,0 +1,15 @@ + + +# Facts: + +Range: `..` + +| Ref | Kind | Title | Status | Epic or goal | Functional area | User outcome | Source | +| --- | --- | --- | --- | --- | --- | --- | --- | +| | | | <status per the sources reference> | <parent epic or roadmap item> | <capability the changed code serves> | <what a user can now do, quoted or paraphrased from the ticket> | <ticket URL, pull request, or commit sha> | + +## Limitations found + +| Ref | Limitation | Source | +| --- | --- | --- | +| <ref> | <what does not work yet or works partly> | <where it was stated> | diff --git a/plugins/aidd-pm/skills/12-release-notes/assets/release-notes-template.md b/plugins/aidd-pm/skills/12-release-notes/assets/release-notes-template.md new file mode 100644 index 000000000..8fd7893f1 --- /dev/null +++ b/plugins/aidd-pm/skills/12-release-notes/assets/release-notes-template.md @@ -0,0 +1,45 @@ +--- +type: release-notes +release: <release name or version> +range: <from>..<to> +audience: <internal or customer> +status: draft +--- + +<!-- Release notes template. Keep and word each section per the audiences reference, drop the sections the audience omits, never add or reorder one, strip this comment. --> + +# <Product name> <release> + +<One or two sentences: what this release lets users do.> + +## Scope + +| Item | Type | Status | Ref | +| --- | --- | --- | --- | +| <title> | <story, task, defect, or change> | <status> | <ticket or pull request> | + +## What you can do now + +- <One benefit per line, starting with what the user can now do.> + +## Where it fits + +<The epic, goal, or roadmap step this release advances, and what comes next only when a source states it.> + +## Impacted areas + +| Area | What changed | Refs | +| --- | --- | --- | +| <capability the code serves> | <functional summary of the change> | <pull requests or commits> | + +## Known limitations + +- <Limitation, and the workaround when a source gives one.> + +## Demo + +1. <Step a presenter runs, built from a shipped item's acceptance criteria.> + +## Open questions + +- <TBD marker, one per gap.> diff --git a/plugins/aidd-pm/skills/12-release-notes/references/audiences.md b/plugins/aidd-pm/skills/12-release-notes/references/audiences.md new file mode 100644 index 000000000..be75ee83b --- /dev/null +++ b/plugins/aidd-pm/skills/12-release-notes/references/audiences.md @@ -0,0 +1,34 @@ +# Audiences + +## Sections kept + +| Section | Internal | Customer | +| --- | --- | --- | +| Summary | yes | yes | +| Scope | every status, with refs | shipped items only, no refs | +| What you can do now | yes | yes | +| Where it fits | epic and roadmap position | the product area only | +| Impacted areas | yes | omitted | +| Known limitations | all of them | only those a user can hit | +| Demo | yes | optional, when the user asks for it | +| Open questions | yes | omitted; a TBD blocks sharing | + +## Wording + +| Audience | Rule | +| --- | --- | +| both | one benefit per line, starting with what the user can now do | +| both | plain words; no internal code name unless the product uses it | +| internal | code areas named by the capability they serve, never by file path | +| customer | no ticket id, pull request, branch, team name, or internal tool | +| customer | no promise of a future date or feature | + +## Publication risks + +Flag each one for the user; never drop or keep it silently. + +- a security fix whose detail could expose users before they update +- a feature shipped disabled or behind a flag +- a customer, partner, or person named in a ticket +- an item marked partially shipped or not in this release +- a limitation that contradicts a public commitment found in the sources diff --git a/plugins/aidd-pm/skills/12-release-notes/references/handoffs.md b/plugins/aidd-pm/skills/12-release-notes/references/handoffs.md new file mode 100644 index 000000000..e7d140f98 --- /dev/null +++ b/plugins/aidd-pm/skills/12-release-notes/references/handoffs.md @@ -0,0 +1,10 @@ +# Handoffs + +Offer the named capability with what was observed, then stop. Never invoke it silently, never write outside the release notes. + +| Observed | Capability | Return | +| --- | --- | --- | +| the release has no tag or version yet | release tag | the notes resume once the tag exists | +| a product mismatch shipped in the range | Defect | the notes list it as a known limitation | +| shipped work with no ticket that the user wants tracked | Task | the notes keep it as an untracked change | +| no match | none | report what was observed | diff --git a/plugins/aidd-pm/skills/12-release-notes/references/persistence.md b/plugins/aidd-pm/skills/12-release-notes/references/persistence.md new file mode 100644 index 000000000..4da76f292 --- /dev/null +++ b/plugins/aidd-pm/skills/12-release-notes/references/persistence.md @@ -0,0 +1,10 @@ +# Persistence + +| Situation | Result | +| --- | --- | +| explicit target | use it | +| notes exist for this release and audience | update them and keep their identity | +| no target given | write `aidd_docs/releases/<release-slug>/<audience>.md`, the release name in kebab-case | +| the user declines a write | keep the notes in the session | + +Markdown is the only support this skill writes. diff --git a/plugins/aidd-pm/skills/12-release-notes/references/sources.md b/plugins/aidd-pm/skills/12-release-notes/references/sources.md new file mode 100644 index 000000000..788ec2d0b --- /dev/null +++ b/plugins/aidd-pm/skills/12-release-notes/references/sources.md @@ -0,0 +1,42 @@ +# Sources + +## Release range + +| Given | Range | +| --- | --- | +| two refs | the first ref to the second | +| one tag or version | the tag before it to that tag | +| a release name only | the tag matching it, else ask for the refs | +| nothing | the latest tag to `HEAD`, confirmed with the user before use | +| no tag exists | ask for the refs; never assume a start | + +## Where each fact comes from + +| Fact | Source, in order | +| --- | --- | +| merged pull requests | the configured VCS tool for the range, else merge commits in `git log <from>..<to>` | +| commits and changed paths | `git log` and `git diff --stat` on the range | +| ticket ids | the given list, then pull request titles and bodies, branch names, and commit messages, per the project's ticketing convention | +| ticket records | the configured ticketing tool, else tickets pasted by the user | +| epic, PRD, product brief, roadmap | the tracker parent of each ticket, then matching files under `aidd_docs/` | + +## Configured tools + +| Source, in order | Holds | +| --- | --- | +| project memory | the configured ticketing and VCS tools | +| repo configuration | fallback | +| environment | fallback | +| the remote URL | the VCS tool only | + +When no ticketing tool resolves, ask the user to paste the ticket list. + +## Ticket status + +| Observed | Recorded as | +| --- | --- | +| ticket done and its change merged in the range | shipped | +| change merged in the range, ticket still open | partially shipped | +| ticket listed, no change merged in the range | not in this release | +| change merged in the range, no ticket found | untracked change | +| change merged behind a feature flag the sources name | shipped, disabled by default | diff --git a/plugins/aidd-pm/skills/12-release-notes/references/tbd-marker.md b/plugins/aidd-pm/skills/12-release-notes/references/tbd-marker.md new file mode 100644 index 000000000..9cbcbda63 --- /dev/null +++ b/plugins/aidd-pm/skills/12-release-notes/references/tbd-marker.md @@ -0,0 +1,3 @@ +# TBD marker + +`TBD: <precise question>` diff --git a/plugins/aidd-pm/skills/13-data-driven-decision/SKILL.md b/plugins/aidd-pm/skills/13-data-driven-decision/SKILL.md new file mode 100644 index 000000000..75df21435 --- /dev/null +++ b/plugins/aidd-pm/skills/13-data-driven-decision/SKILL.md @@ -0,0 +1,45 @@ +--- +name: 13-data-driven-decision +description: Produces a reproducible evidence dashboard and decision memo from customer signals for a pending product decision. Use when the user wants to decide, prioritize, or settle a debate with data rather than intuition. Not for analytics setup. +argument-hint: decision | tracking plan +--- + +# Data-Driven Decision + +```mermaid +flowchart LR + source([decision or tracking plan]) --> interview --> plan + source -->|"approved plan exists"| collect + interview -->|"no decision at stake"| none([handoff, nothing built]) + plan -->|"revise frame"| interview + plan -->|"approved"| collect --> dashboard --> memo + collect -->|"definition gap"| plan + dashboard -->|"widen sources or window"| plan + memo -->|"more evidence"| collect + memo -->|"handed back"| done([dashboard and memo]) +``` + +## Actions + +Run the flow above. Read only the next action file. + +| Action | Does | +| --------- | --------------------------------------------- | +| interview | frame the decision and what would change it | +| plan | define topics, sources, and counting rules | +| collect | gather and classify matching items | +| dashboard | count, quote, and rate confidence per topic | +| memo | weigh the options and hand the decision back | + +## Transversal rules + +- Keep product and lifecycle decisions with the user. +- Separate evidence, decisions, and assumptions. +- Preserve source links and existing edits. +- Ask natural questions; never expose actions, references, or unchanged state. +- Require explicit approval or caller-provided bounded authority before any write. +- Collect nothing and build no dashboard before the tracking plan is approved. +- Quote only exact words read in a source; never invent, merge, or reword a quote. +- Make every count reproducible from the approved plan and the ledger. +- Say plainly when the data is too thin to conclude. +- Inform the decision; the PM makes it. diff --git a/plugins/aidd-pm/skills/13-data-driven-decision/actions/01-interview.md b/plugins/aidd-pm/skills/13-data-driven-decision/actions/01-interview.md new file mode 100644 index 000000000..c45a74b4f --- /dev/null +++ b/plugins/aidd-pm/skills/13-data-driven-decision/actions/01-interview.md @@ -0,0 +1,30 @@ +# 01 - Interview + +Frame the decision with the PM before any data is read. + +## Input + +A pending decision, a topic to track, or the current context. + +## Output + +A decision frame kept in context: question, deadline, options, current belief, change-of-mind criteria, topics, population, sources, and window. + +## Process + +1. **Resolve.** Infer the decision from the current context; otherwise ask what decision is at stake and wait. +2. **Qualify.** When no decision can change with the answer, apply [handoffs](../references/handoffs.md) and stop. +3. **Ask.** Walk [interview](../references/interview.md) one question at a time, skipping what the context already answers. +4. **Anchor.** Restate the PM's current belief and change-of-mind criteria in their words before any source is read. +5. **Inventory.** List the reachable sources per [sources](../references/sources.md) and confirm access to each with the PM. +6. **Confirm.** Show the frame and wait for corrections. + +## Test + +| Case | Pass | +| --- | --- | +| No decision named | exactly one question asked; no source read; workspace unchanged | +| The PM asks for a dashboard right away | the frame questions come first; no item collected | +| Frame shown | it holds at least two options, one being doing nothing, and one change-of-mind criterion | +| A source is unreachable | it is listed as a gap with an export or paste alternative | +| No decision at stake | no frame built; the handoff is offered and the run stops | diff --git a/plugins/aidd-pm/skills/13-data-driven-decision/actions/02-plan.md b/plugins/aidd-pm/skills/13-data-driven-decision/actions/02-plan.md new file mode 100644 index 000000000..5e1e3c44a --- /dev/null +++ b/plugins/aidd-pm/skills/13-data-driven-decision/actions/02-plan.md @@ -0,0 +1,31 @@ +# 02 - Plan + +Turn the frame into a tracking plan the PM approves before anything is counted. + +## Input + +The confirmed decision frame, or an existing tracking plan to revise. + +## Output + +An approved tracking plan per [the template](../assets/tracking-plan.md), persisted per [persistence](../references/persistence.md). + +## Process + +1. **Define.** Fill one topic row per theme: a definition, what counts, what does not, and search keywords. +2. **Source.** Fill one source row per reachable source with its access route and the exact query, filter, or file. +3. **Rule.** Set the units, deduplication, time buckets, and thresholds per [counting](../references/counting.md) and [confidence](../references/confidence.md). +4. **Calibrate.** Read up to ten items from one source without recording them, show which match each definition and which do not, and sharpen the definitions with the PM. +5. **Show.** Present the full plan and wait for approval or revision. + - A revision that changes the decision, options, or population returns to `interview`. +6. **Persist.** When the PM authorizes a write, save the approved plan with `status: approved` and read it back. + +## Test + +| Case | Pass | +| --- | --- | +| Topic row | definition, counts, does not count, and keywords are all filled | +| Source row | a query, filter, or file name that a second person could rerun | +| Plan not approved | no collection run; workspace unchanged | +| Plan approved and write authorized | the written plan carries `status: approved` and a `version` | +| Approved plan changed | `version` incremented; any earlier dashboard is marked stale | diff --git a/plugins/aidd-pm/skills/13-data-driven-decision/actions/03-collect.md b/plugins/aidd-pm/skills/13-data-driven-decision/actions/03-collect.md new file mode 100644 index 000000000..4c8a61365 --- /dev/null +++ b/plugins/aidd-pm/skills/13-data-driven-decision/actions/03-collect.md @@ -0,0 +1,32 @@ +# 03 - Collect + +Gather the items the plan points to and classify each one against the topic definitions. + +## Input + +An approved tracking plan. + +## Output + +An evidence ledger per [the template](../assets/evidence-ledger.md), with its collection log and exclusions. + +## Process + +1. **Access.** Resolve each source's route per [sources](../references/sources.md). +2. **Fetch.** Run the plan's query over the window, follow pagination, and log the query, read date, returned count, and completeness. +3. **Classify.** Match each item against the topic definitions per [counting](../references/counting.md) and record topic, kind, voice, date, and link. +4. **Mark.** In a verbatim, mark any cut with `[...]` and any translation as such. +5. **Exclude.** Log every keyword hit that fails a definition, with its reason. +6. **Spot-check.** Show the PM ten ledger rows picked at random and record how many classifications they confirm. + - When items keep failing to fit a definition, return to `plan` instead of forcing a topic. + +## Test + +| Case | Pass | +| --- | --- | +| Ledger row | source, link or file locator, date, voice, topic, and kind are all filled | +| Verbatim | the quoted string is found as is in the linked item | +| Same plan and sources rerun | same ledger rows and same counts | +| Source partly read | its collection log row reads incomplete, with the reason | +| Keyword hit without the meaning | listed under exclusions, not counted | +| Spot-check | agreement recorded as confirmed out of checked | diff --git a/plugins/aidd-pm/skills/13-data-driven-decision/actions/04-dashboard.md b/plugins/aidd-pm/skills/13-data-driven-decision/actions/04-dashboard.md new file mode 100644 index 000000000..b18444dab --- /dev/null +++ b/plugins/aidd-pm/skills/13-data-driven-decision/actions/04-dashboard.md @@ -0,0 +1,35 @@ +# 04 - Dashboard + +Compute the per-topic picture from the ledger and show where it holds and where it does not. + +## Input + +The approved tracking plan and its evidence ledger. + +## Output + +A dashboard per [the template](../assets/dashboard.md), kept in context, with an optional Mermaid chart and an optional CSV of the ledger. + +## Process + +1. **Count.** Compute comments, verbatims, and distinct voices per topic by filtering the ledger per [counting](../references/counting.md). +2. **Trend.** Split each topic's counts into the plan's time buckets. +3. **Select.** Pick representative verbatims that cover different voices and sources, and add at least one counter-signal when the ledger holds one. +4. **Rate.** Rate each topic and name its gaps per [confidence](../references/confidence.md). +5. **Render.** Fill the template with one topic section per plan topic. + - Chart asked: add one Mermaid `xychart-beta` bar chart of counts per topic or per bucket. + - No chart asked: omit the `Chart` section. + - Spreadsheet asked: export the ledger as CSV, one row per ledger row, same columns. +6. **Show.** Present the dashboard and wait. + - Too thin or a coverage gap the PM wants closed: return to `plan`. + +## Test + +| Case | Pass | +| --- | --- | +| Any count recomputed from the ledger | equals the dashboard figure | +| Quote | carries its ledger ID and a source link | +| Topic below the plan's threshold | rated insufficient; no trend claimed | +| Mermaid chart | syntax parses; figures match the summary table | +| CSV | row count equals ledger row count; same columns | +| Reproduce section | names the plan version, the sources read, and the read dates | diff --git a/plugins/aidd-pm/skills/13-data-driven-decision/actions/05-memo.md b/plugins/aidd-pm/skills/13-data-driven-decision/actions/05-memo.md new file mode 100644 index 000000000..9c4731fa2 --- /dev/null +++ b/plugins/aidd-pm/skills/13-data-driven-decision/actions/05-memo.md @@ -0,0 +1,33 @@ +# 05 - Memo + +Weigh each option against the evidence and hand the decision back to the PM. + +## Input + +The decision frame, the dashboard, and the ledger. + +## Output + +A decision memo per [the template](../assets/decision-memo.md), persisted with the dashboard and ledger per [persistence](../references/persistence.md). After a write, report the written paths, the plan version, and the read-back result. Without a write, state that no persisted change occurred. + +## Process + +1. **Map.** For each option, list the evidence for and against it, citing topic, count, and ledger IDs. +2. **Test.** Compare the evidence with the change-of-mind criteria set during the interview and state whether each was met. +3. **Bound.** Write what the data does not say: gaps, silent populations, source bias, and questions left open. +4. **Lean.** State which option the evidence favors and at what confidence, or state that the data is too thin to favor any. +5. **Hand back.** Present the memo, ask the PM for their decision and rationale, and record them in their words. + - The PM wants more evidence: return to `collect` with the named source or window. +6. **Persist.** Write the memo, dashboard, and ledger when authorized, then read them back. +7. **Continue.** Apply [handoffs](../references/handoffs.md) to the next move. + +## Test + +| Case | Pass | +| --- | --- | +| Option row | holds evidence for and against, or reads `none found` | +| Evidence claim | traces to a dashboard topic and ledger IDs | +| Decision field | holds the PM's words or `pending`, never a choice made by the run | +| Data too thin | the memo says so before any lean | +| Unauthorized | workspace unchanged; the response states no persisted change | +| Authorized write | memo, dashboard, and ledger exist at the persistence path and read back | diff --git a/plugins/aidd-pm/skills/13-data-driven-decision/assets/dashboard.md b/plugins/aidd-pm/skills/13-data-driven-decision/assets/dashboard.md new file mode 100644 index 000000000..21df5e9eb --- /dev/null +++ b/plugins/aidd-pm/skills/13-data-driven-decision/assets/dashboard.md @@ -0,0 +1,47 @@ +--- +decision: "<The decision in one question.>" +plan_version: <version of the approved plan> +status: current +--- + +# Dashboard: <decision title> + +<Window, number of sources read, number of ledger items, and the one-line headline the counts support.> + +## Summary + +| Topic | Comments | Verbatims | Distinct voices | Source kinds | Trend | Confidence | +| --- | --- | --- | --- | --- | --- | --- | +| <topic> | <n> | <n> | <n> | <n> | <rising, stable, falling, or not claimed> | <high, medium, low, or insufficient> | + +## <Topic> + +<Definition from the plan.> + +| Bucket | Comments | Verbatims | Distinct voices | +| --- | --- | --- | --- | +| <week or month> | <n> | <n> | <n> | + +Representative quotes: + +> "<exact words>" <account or role>, <date>, <source link> (<ledger ID>) + +Counter-signal: + +> "<exact words>" <account or role>, <date>, <source link> (<ledger ID>) + +Gaps: <gaps for this topic> + +## Chart + +<Mermaid bar chart of counts per topic or per bucket.> + +## Coverage and Gaps + +<Sources not reached, partial reads, missing populations, and known biases across the whole dashboard.> + +## Reproduce + +- Plan: <path and version> +- Sources read: <source, query, read date, one per line> +- Ledger: <path>; every figure above is a filter over it by topic, kind, and bucket diff --git a/plugins/aidd-pm/skills/13-data-driven-decision/assets/decision-memo.md b/plugins/aidd-pm/skills/13-data-driven-decision/assets/decision-memo.md new file mode 100644 index 000000000..d7e4858fa --- /dev/null +++ b/plugins/aidd-pm/skills/13-data-driven-decision/assets/decision-memo.md @@ -0,0 +1,40 @@ +--- +decision: "<The decision in one question.>" +plan_version: <version of the approved plan> +status: current +decided: <pending, or the date the PM decided> +--- + +# Decision Memo: <decision title> + +<The decision, its deadline, and the dashboard it rests on, in one or two sentences.> + +## Options + +| Option | Evidence for | Evidence against | Confidence | +| --- | --- | --- | --- | +| <option> | <topic, count, ledger IDs, or none found> | <topic, count, ledger IDs, or none found> | <level> | + +## Against the Prior + +- Belief before the data: <from the plan> +- Would change my mind: <from the plan> +- Met: <yes, no, or partly, with the figures> + +## What the Data Does Not Say + +- <gap, silent population, bias, or open question> + +## Lean + +<Which option the evidence favors and at what confidence, or that the data is too thin to favor any.> + +## Decision + +- Decided by: <PM name or role> +- Choice: <the PM's choice in their words, or pending> +- Rationale: <the PM's reasons in their words> + +## Next Evidence + +- <the next source, window, or interview that would most reduce the remaining uncertainty> diff --git a/plugins/aidd-pm/skills/13-data-driven-decision/assets/evidence-ledger.md b/plugins/aidd-pm/skills/13-data-driven-decision/assets/evidence-ledger.md new file mode 100644 index 000000000..a2e74a3ed --- /dev/null +++ b/plugins/aidd-pm/skills/13-data-driven-decision/assets/evidence-ledger.md @@ -0,0 +1,28 @@ +--- +decision: "<The decision in one question.>" +plan_version: <version of the approved plan> +--- + +# Evidence Ledger: <decision title> + +## Items + +| ID | Source | Link | Date | Voice | Topic | Kind | Quote or summary | +| --- | --- | --- | --- | --- | --- | --- | --- | +| <E001> | <source> | <URL or file locator> | <date spoken> | <account or role> | <topic> | <comment or verbatim> | <exact quote for a verbatim, one-line summary for a comment> | + +## Collection Log + +| Source | Query, filter, or file | Read on | Returned | Complete | +| --- | --- | --- | --- | --- | +| <source> | <as in the plan> | <date> | <count> | <yes, or no and why> | + +## Exclusions + +| Source | Link | Reason | +| --- | --- | --- | +| <source> | <URL or file locator> | <keyword only, out of window, duplicate, or out of population> | + +## Spot-Check + +<Confirmed> of <checked> classifications confirmed by the PM on <date>. diff --git a/plugins/aidd-pm/skills/13-data-driven-decision/assets/tracking-plan.md b/plugins/aidd-pm/skills/13-data-driven-decision/assets/tracking-plan.md new file mode 100644 index 000000000..57cf49a65 --- /dev/null +++ b/plugins/aidd-pm/skills/13-data-driven-decision/assets/tracking-plan.md @@ -0,0 +1,44 @@ +--- +decision: "<The decision in one question.>" +status: draft +version: 1 +window: "<start date> to <end date>" +--- + +# Tracking Plan: <decision title> + +## Decision + +- Question: <the decision to make> +- Deadline: <date or event> +- Options: <option A>; <option B>; do nothing +- Current belief: <what the PM believes today, and on what basis> +- Would change my mind: <the evidence that would move the PM, in their words> +- Stakes: <what a wrong call costs> + +## Population + +<Whose voice counts, and whose does not.> + +## Topics + +| Topic | Definition | Counts | Does not count | Keywords | +| --- | --- | --- | --- | --- | +| <topic> | <one-sentence definition> | <example that fits> | <near miss that does not> | <search terms> | + +## Sources + +| Source | Route | Query, filter, or file | Access held by | +| --- | --- | --- | --- | +| <source> | <connected tool, export, or paste> | <exact query or file name> | <person or role> | + +## Counting Rules + +- Buckets: <week or month> +- Minimum count per bucket for a trend: <number> +- Confidence thresholds: <defaults kept, or the changes made> +- Deduplication: <any rule beyond the defaults> + +## Out of Scope + +- <what this plan deliberately does not track> diff --git a/plugins/aidd-pm/skills/13-data-driven-decision/references/confidence.md b/plugins/aidd-pm/skills/13-data-driven-decision/references/confidence.md new file mode 100644 index 000000000..f1f8647eb --- /dev/null +++ b/plugins/aidd-pm/skills/13-data-driven-decision/references/confidence.md @@ -0,0 +1,24 @@ +# Confidence + +Default thresholds. The tracking plan may change them before collection, never after. + +| Level | All of | Say | +| --- | --- | --- | +| High | 20 or more distinct voices, 3 or more source kinds, full window read, spot-check at least 8 of 10 | the signal is consistent across sources | +| Medium | 10 or more distinct voices, 2 or more source kinds | the signal is real; its size is uncertain | +| Low | 5 or more distinct voices | a lead worth checking, not a basis to decide | +| Insufficient | anything less, or one source holding the whole count | too thin to conclude | + +## Gaps + +Name every gap that applies, per topic. + +| Gap | Example | +| --- | --- | +| Source not reached | no access to the support desk | +| Partial read | results capped at the first 100 items | +| Missing population | churned accounts never interviewed | +| Selection bias | support tickets only capture problems | +| Relayed only | every comment comes second-hand through the sales team | +| Ambiguous definition | spot-check agreement below 8 of 10 | +| Short window | fewer buckets than needed to read a trend | diff --git a/plugins/aidd-pm/skills/13-data-driven-decision/references/counting.md b/plugins/aidd-pm/skills/13-data-driven-decision/references/counting.md new file mode 100644 index 000000000..7a4145e12 --- /dev/null +++ b/plugins/aidd-pm/skills/13-data-driven-decision/references/counting.md @@ -0,0 +1,23 @@ +# Counting + +## Units + +| Unit | Counts | Does not count | +| --- | --- | --- | +| Item | one ticket, message, email, note, review, or transcript passage read from a source | a reply that only quotes an earlier item | +| Comment | an item where a voice from the plan's population speaks to a topic, first-hand or relayed | a team member's own opinion | +| Verbatim | a comment holding that voice's exact words, first-hand | a paraphrase, a summary, or a relayed quote | +| Distinct voice | one customer or account, counted once per topic | the same account seen in several items | + +## Rules + +| Rule | Applies as | +| --- | --- | +| Meaning over keyword | an item joins a topic when it meets the definition; a keyword hit alone is excluded and logged | +| One item, one count per topic | an item may join several topics, once each | +| Duplicates | the same statement forwarded or copied counts once, at its earliest date | +| Date | the date the voice spoke, not the date the item was filed | +| Window | items dated outside the plan's window are excluded and logged | +| Buckets | week or month, as set in the plan, never changed after collection | +| Trend | claimed only when every bucket compared meets the plan's minimum count | +| Reproducibility | every figure equals a filter over the ledger; the dashboard names the plan version and read dates | diff --git a/plugins/aidd-pm/skills/13-data-driven-decision/references/handoffs.md b/plugins/aidd-pm/skills/13-data-driven-decision/references/handoffs.md new file mode 100644 index 000000000..296e07a3d --- /dev/null +++ b/plugins/aidd-pm/skills/13-data-driven-decision/references/handoffs.md @@ -0,0 +1,12 @@ +# Handoffs + +Offer the named capability with what was observed, then stop. Never invoke it silently. + +| Observed | Capability | Return | +| --- | --- | --- | +| no decision can change with the answer | none | report what was observed | +| data too thin and the decision cannot wait for more | Spike | one-way; the memo is its evidence | +| a population is silent or known only second-hand | user interviews | back to `collect` with the syntheses | +| decision taken to explore a new opportunity | Product Brief | one-way; the memo is its evidence | +| decision taken to build | Epic or User Story | one-way | +| a topic is a product malfunction | Defect | one-way | diff --git a/plugins/aidd-pm/skills/13-data-driven-decision/references/interview.md b/plugins/aidd-pm/skills/13-data-driven-decision/references/interview.md new file mode 100644 index 000000000..465baaeb0 --- /dev/null +++ b/plugins/aidd-pm/skills/13-data-driven-decision/references/interview.md @@ -0,0 +1,22 @@ +# Interview + +Ask in this order, one question per turn. Skip a row the context already answers. + +| Topic | Ask | Why it matters | +| --- | --- | --- | +| Decision | What decision do you have to make, and by when? | a dashboard without a decision measures nothing | +| Options | Which options are on the table, including doing nothing? | evidence is weighed per option, not in general | +| Current belief | What do you believe today, and what is it based on? | exposes the intuition the data will test | +| Change of mind | What would you need to see to change your mind? | sets the bar before the data, so it cannot move after | +| Topics | Which themes or problems should we track? | each topic becomes one counted row | +| Population | Whose voice counts: customers, prospects, churned accounts, internal teams? | fixes who a comment must come from | +| Sources | Where do these signals live today? | bounds what can be collected | +| Window | Over which period, and why that one? | makes counts comparable and trends readable | +| Stakes | What does a wrong call cost? | sets the confidence the decision needs | + +| Case | Handling | +| --- | --- | +| The PM names topics but no decision | ask for the decision first | +| The PM wants the dashboard now | explain that counts need agreed definitions, then continue with the next question | +| The answer is a solution, not a decision | ask which problem it solves and what the alternative is | +| The PM has no change-of-mind criterion | offer two concrete examples drawn from their options and ask them to pick or adapt | diff --git a/plugins/aidd-pm/skills/13-data-driven-decision/references/persistence.md b/plugins/aidd-pm/skills/13-data-driven-decision/references/persistence.md new file mode 100644 index 000000000..9404991f9 --- /dev/null +++ b/plugins/aidd-pm/skills/13-data-driven-decision/references/persistence.md @@ -0,0 +1,18 @@ +# Persistence + +Write under `aidd_docs/product/decisions/<decision-slug>/`, the slug in kebab-case. + +| File | Holds | +| --- | --- | +| `tracking-plan.md` | the approved plan | +| `ledger.md` | the evidence ledger, collection log, and exclusions | +| `dashboard.md` | the dashboard for one plan version | +| `memo.md` | the decision memo | +| `ledger.csv` | optional export of the ledger | + +| Situation | Result | +| --- | --- | +| New decision | create the folder | +| Same decision, plan unchanged, new collection | overwrite ledger and dashboard; keep the memo until revised | +| Plan revised after approval | increment `version`; mark the previous dashboard and memo `stale` | +| Existing file edited by the user | preserve the edit; change only generated sections | diff --git a/plugins/aidd-pm/skills/13-data-driven-decision/references/sources.md b/plugins/aidd-pm/skills/13-data-driven-decision/references/sources.md new file mode 100644 index 000000000..c87dc7e7e --- /dev/null +++ b/plugins/aidd-pm/skills/13-data-driven-decision/references/sources.md @@ -0,0 +1,33 @@ +# Sources + +Use each source only for what it can support. + +| Source | Typical items | Can support | Cannot establish | +| --- | --- | --- | --- | +| Ticketing tool | issues, requests, comments | recurring asks and their volume | why users ask, or who never asks | +| Support desk | tickets, chats | pain and friction as reported | the silent majority | +| Team wiki | meeting notes, research pages | what the team recorded | what customers said verbatim, unless quoted | +| Email | customer threads | first-hand statements | frequency across the base | +| Team chat | channel messages, forwarded feedback | fresh signals and reported quotes | first-hand wording, when relayed | +| Meeting transcripts | sales, success, or discovery calls | exact customer words in context | calls that were not recorded | +| Interview syntheses | themes and quotes from user interviews | depth on a few voices | prevalence | +| Reviews and surveys | app store reviews, NPS or CSAT verbatims | public or scored sentiment | intent of non-respondents | + +## Access + +Try each route in order and record the one used. + +| Order | Route | Record | +| --- | --- | --- | +| 1 | a connected tool, found by the capability it offers | tool, query, read date | +| 2 | the ticketing tool configured in project memory, then repo configuration, then environment | tool, query, read date | +| 3 | an export file the PM provides | file name, export date | +| 4 | content the PM pastes | who pasted it, paste date | +| 5 | none reachable | a coverage gap | + +| Case | Handling | +| --- | --- | +| Results are paginated or capped | follow every page, or record the source as incomplete | +| A source needs rights the PM lacks | record the gap and name who holds access | +| Items hold personal data | keep the account or role as the voice; copy no email, phone, or address | +| A relayed quote has no first-hand source | count it as a comment, never as a verbatim | diff --git a/plugins/aidd-pm/skills/14-roadmap/SKILL.md b/plugins/aidd-pm/skills/14-roadmap/SKILL.md new file mode 100644 index 000000000..7a746f6db --- /dev/null +++ b/plugins/aidd-pm/skills/14-roadmap/SKILL.md @@ -0,0 +1,45 @@ +--- +name: 14-roadmap +description: Builds or updates a quarterly product roadmap from Epics, Product Briefs, tickets, and decisions, with team and stakeholder views. Use when the user wants to plan a quarter, present its roadmap, or check it against progress. Not for sprint planning. +argument-hint: quarter | roadmap +--- + +# Roadmap + +```mermaid +flowchart LR + quarter([quarter to plan]) --> frame --> collect --> arrange --> render --> finalize + roadmap([persisted roadmap]) --> track + frame -->|"quarter already planned"| track + track -->|"new candidates"| collect + track -->|"replan"| arrange + track -->|"on track"| report([progress report]) + collect -->|"no candidate"| stop([one open question]) + render -->|"revise"| arrange + finalize -->|"revise"| arrange + finalize -->|"authorized"| done([quarterly roadmap and stakeholder view]) +``` + +## Actions + +Run the flow above. Read only the next action file. + +| Action | Does | +| -------- | -------------------------------------------- | +| frame | fix the quarter, capacity, and audiences | +| collect | gather traced candidates and their outcomes | +| track | compare the roadmap with actual progress | +| arrange | place the items the user prioritizes | +| render | draw the diagram, table, and audience views | +| finalize | approve and persist both views | + +## Transversal rules + +- Keep priority, placement, and commitment decisions with the user. +- Never invent a date, priority, estimate, capacity, or commitment; ask for the missing one. +- Trace every item to its Epic, Product Brief, ticket, or decision, or mark it as a proposal. +- Separate evidence, decisions, and assumptions. +- Preserve source links and existing edits. +- Ask natural questions; never expose actions, references, or unchanged state. +- Require explicit approval or caller-provided bounded authority before any write. +- Stay at outcome level; never slice an item into Stories or tasks. diff --git a/plugins/aidd-pm/skills/14-roadmap/actions/01-frame.md b/plugins/aidd-pm/skills/14-roadmap/actions/01-frame.md new file mode 100644 index 000000000..eb77ad139 --- /dev/null +++ b/plugins/aidd-pm/skills/14-roadmap/actions/01-frame.md @@ -0,0 +1,32 @@ +# 01 - Frame + +Fix the quarter, its capacity and constraints, and the audiences before any item is placed. + +## Input + +The quarter to plan, a product scope, or current context. + +## Output + +A confirmed frame: quarter label and dates, product scope, granularity, capacity, constraints, and audiences. + +## Process + +1. **Resolve.** Read the quarter, product scope, and any existing roadmap for that quarter per [persistence](../references/persistence.md). + - An existing roadmap for the same quarter: offer to update it instead, and hand it to `track` on a yes. +2. **Quarter.** Ask for the quarter and whether it follows the calendar or a fiscal year, when the input does not state it. +3. **Granularity.** Ask whether items land on a month or on a now, next, later horizon, per [placement](../references/placement.md). +4. **Capacity.** Ask for the team capacity, in the unit the team already uses, and the known constraints: fixed dates, holidays, shared people, external commitments. + - No capacity given: record capacity as unknown. +5. **Audiences.** Ask who receives the stakeholder view, and what it must leave out. +6. **Confirm.** Show the frame in a few lines and fold corrections. + +## Test + +| Case | Pass | +| --- | --- | +| The run completes | `git status --porcelain` reads the same after as before | +| Quarter not stated | one question asks for it; no quarter is assumed from today's date | +| Capacity not given | the frame records capacity as unknown; no figure appears | +| Roadmap exists for the quarter | the update path is offered before any new draft | +| Frame confirmed | every field holds a user-given value or an explicit unknown | diff --git a/plugins/aidd-pm/skills/14-roadmap/actions/02-collect.md b/plugins/aidd-pm/skills/14-roadmap/actions/02-collect.md new file mode 100644 index 000000000..ce9fa4fdd --- /dev/null +++ b/plugins/aidd-pm/skills/14-roadmap/actions/02-collect.md @@ -0,0 +1,32 @@ +# 02 - Collect + +Gather the candidate items for the quarter, each with its outcome and its source. + +## Input + +The confirmed frame, or the new candidates `track` surfaced. + +## Output + +A candidate list: one row per item with its outcome, theme, source status, estimate when the source holds one, dependencies, and trace. + +## Process + +1. **Read.** Read every source in [sources](../references/sources.md) that the project holds, within the product scope. +2. **Extract.** Keep, per item, only what its source states: outcome, status, estimate, dependencies, and date. + - A field the source does not state stays empty. +3. **Trace.** Record the source identity of each item, or `proposal` when it has none. +4. **Group.** Propose themes from the outcomes the sources state, and let the user rename, merge, or split them. +5. **Gap.** Apply [handoffs](../references/handoffs.md) to an item that has no outcome or no framed opportunity. +6. **Show.** Present the list, grouped by theme, and ask what is missing. + - No candidate found: ask one open question for the outcomes the quarter should serve, then stop. + +## Test + +| Case | Pass | +| --- | --- | +| The run completes | `git status --porcelain` reads the same after as before | +| An item from a source | its trace names a real Epic path, Product Brief path, ticket id, or decision record | +| An item the user adds | its trace reads `proposal` | +| A source without an estimate | the estimate cell is empty; no size is proposed | +| No source holds a candidate | no list; one open question | diff --git a/plugins/aidd-pm/skills/14-roadmap/actions/03-track.md b/plugins/aidd-pm/skills/14-roadmap/actions/03-track.md new file mode 100644 index 000000000..a1564bf8e --- /dev/null +++ b/plugins/aidd-pm/skills/14-roadmap/actions/03-track.md @@ -0,0 +1,33 @@ +# 03 - Track + +Compare a persisted roadmap with the actual progress of its items and flag every drift. + +## Input + +A persisted roadmap, and today's date. + +## Output + +A progress report: one row per item with its planned placement, its current source status, and its flag, then the new candidates found. + +## Process + +1. **Load.** Read the roadmap per [persistence](../references/persistence.md). +2. **Refresh.** Read the current status of each traced item from its source, per [sources](../references/sources.md). +3. **Flag.** Apply [progress](../references/progress.md) to every item, against today's date. +4. **Spot.** List source items created or moved into scope since the roadmap was approved, and not on it. +5. **Report.** Show the flagged items first, each with its evidence, then ask whether to replan, add candidates, or keep the roadmap. + - Replan: hand the report to `arrange`. + - New candidates: hand them to `collect`. + - Keep: end with the report; no write. + +## Test + +| Case | Pass | +| --- | --- | +| The run completes | `git status --porcelain` reads the same after as before | +| An item past its month and not done | it is flagged `slipped`, with its source status quoted | +| A source cancelled | the item is flagged `dropped`; it is not removed | +| A flag | it cites the source status and the date it was read | +| An Epic whose children are closed | it is not reported done without its source status saying so | +| No drift | the report states that every item is on track | diff --git a/plugins/aidd-pm/skills/14-roadmap/actions/04-arrange.md b/plugins/aidd-pm/skills/14-roadmap/actions/04-arrange.md new file mode 100644 index 000000000..d40ec9bb8 --- /dev/null +++ b/plugins/aidd-pm/skills/14-roadmap/actions/04-arrange.md @@ -0,0 +1,34 @@ +# 04 - Arrange + +Place the items the user prioritizes into the quarter, by theme and by month or horizon. + +## Input + +The confirmed frame and the candidate list, or the progress report of a replan. + +## Output + +An approved arrangement: each kept item with its theme, placement, commitment, and trace, plus the items left out. + +## Process + +1. **Ask.** Ask the user which outcomes matter most this quarter, and in what order. + - Offer only the order signals the sources support, per [placement](../references/placement.md), with no default. +2. **Place.** Put each kept item in the month or horizon the user gives, per [placement](../references/placement.md). + - Replan: show each flagged item next to its current placement, and let the user move, keep, or drop it. +3. **Commit.** Ask the commitment level of each item, per [placement](../references/placement.md). +4. **Fit.** Compare the summed estimates of each month or horizon with the capacity, when both are known. + - Either is unknown: state that fit cannot be checked, and ask whether to continue. + - Overload: name the month and the gap, and let the user cut, move, or accept it. +5. **Confirm.** Show the arrangement as a table, then the items left out, and fold corrections until approved. + +## Test + +| Case | Pass | +| --- | --- | +| The run completes | `git status --porcelain` reads the same after as before | +| An item placed | its placement and commitment were given by the user, never inferred | +| A proposal placed | it keeps its `proposal` trace | +| Capacity or estimates missing | no fit verdict; the gap is stated | +| An overload | the month and the gap are named; no item is moved without the user | +| Replan | every flagged item has a user decision: move, keep, or drop | diff --git a/plugins/aidd-pm/skills/14-roadmap/actions/05-render.md b/plugins/aidd-pm/skills/14-roadmap/actions/05-render.md new file mode 100644 index 000000000..1e1b29c6b --- /dev/null +++ b/plugins/aidd-pm/skills/14-roadmap/actions/05-render.md @@ -0,0 +1,31 @@ +# 05 - Render + +Draw the approved arrangement as a diagram and a table, in a team view and a stakeholder view. + +## Input + +The approved arrangement and the confirmed frame. + +## Output + +Two drafts: the team roadmap per [roadmap template](../assets/roadmap-template.md), and the stakeholder view per [stakeholder template](../assets/stakeholder-template.md). + +## Process + +1. **Diagram.** Pick the chart per [views](../references/views.md), and generate it through the Mermaid diagram capability when one is installed, the approved arrangement standing as its confirmed plan. + - None installed: generate it per [views](../references/views.md). +2. **Team.** Fill [roadmap template](../assets/roadmap-template.md) with the diagram and the full table. +3. **Stakeholder.** Fill [stakeholder template](../assets/stakeholder-template.md) per [audiences](../references/audiences.md). +4. **Show.** Present both drafts and ask for corrections. + - A change of placement or commitment: return to `arrange`. + +## Test + +| Case | Pass | +| --- | --- | +| The run completes | `git status --porcelain` reads the same after as before | +| The diagram | it sits in a fenced `mermaid` block and parses in Mermaid 10.8.0 or newer | +| The diagram is read back | every bar or entry matches a table row; none is added | +| The team view | every row carries a trace or `proposal` | +| The stakeholder view | no ticket id, estimate, capacity, or excluded item appears | +| Either draft is read back | no `<` placeholder and no template comment survives | diff --git a/plugins/aidd-pm/skills/14-roadmap/actions/06-finalize.md b/plugins/aidd-pm/skills/14-roadmap/actions/06-finalize.md new file mode 100644 index 000000000..95375eaa7 --- /dev/null +++ b/plugins/aidd-pm/skills/14-roadmap/actions/06-finalize.md @@ -0,0 +1,30 @@ +# 06 - Finalize + +Approve the roadmap and persist both views, or keep them in the session. + +## Input + +The two drafts, and the authority for a write. + +## Output + +Both views in the session or at their resolved paths. After a write, report each path, changed fields as `before -> after`, and the verification result. Without a write, state that no persisted change occurred. + +## Process + +1. **Authorize.** Use caller-provided bounded authority, or ask whether to keep the drafts in the session or persist them, and wait. +2. **Place.** Resolve both paths per [persistence](../references/persistence.md). +3. **Log.** On an update, add one entry per changed item to the team view's change log, with the reason the user gave. +4. **Write.** Write both views; preserve user edits outside the authorized change. +5. **Verify.** Read both files back and report what changed. +6. **Continue.** Apply [handoffs](../references/handoffs.md) to any open gap. + +## Test + +| Case | Pass | +| --- | --- | +| Unauthorized | workspace unchanged; response ends with one session-or-persist question | +| First write | both files exist at the paths `persistence` gives; the team file reads `status: approved` | +| An update | each changed item has one change-log entry with `before -> after` and a reason | +| User edits outside the change | preserved byte for byte | +| No write | the response states that no persisted change occurred | diff --git a/plugins/aidd-pm/skills/14-roadmap/assets/roadmap-template.md b/plugins/aidd-pm/skills/14-roadmap/assets/roadmap-template.md new file mode 100644 index 000000000..e91fc9900 --- /dev/null +++ b/plugins/aidd-pm/skills/14-roadmap/assets/roadmap-template.md @@ -0,0 +1,41 @@ +<!-- Team roadmap template. Fill every angle-bracket placeholder from the approved arrangement and frame; leave an unknown value as "unknown". Keep the Change log empty on a first write. Remove this comment. --> +--- +type: roadmap +audience: team +quarter: <quarter label> +period: <first day> to <last day> +status: approved +updated: <yyyy-mm-dd> +--- + +# Roadmap: <quarter label> + +<The outcomes this quarter serves, in one or two sentences.> + +## Frame + +- Scope: <product scope> +- Capacity: <capacity and unit, or unknown> +- Constraints: <fixed dates, holidays, shared people, or none> + +## Plan + +```mermaid +<the chart per views> +``` + +| Theme | Item | Outcome | Placement | Commitment | Estimate | Depends on | Trace | Status | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | +| <theme> | <item> | <outcome> | <month or horizon> | <committed, planned, or exploring> | <source estimate or empty> | <predecessor or empty> | <source id or proposal> | <progress flag or empty> | + +## Left out + +| Item | Trace | Reason | +| --- | --- | --- | +| <item> | <source id or proposal> | <the user's reason> | + +## Change log + +| Date | Item | Change | Reason | +| --- | --- | --- | --- | +| <yyyy-mm-dd> | <item> | <old value, then new value> | <the user's reason> | diff --git a/plugins/aidd-pm/skills/14-roadmap/assets/stakeholder-template.md b/plugins/aidd-pm/skills/14-roadmap/assets/stakeholder-template.md new file mode 100644 index 000000000..152b9286a --- /dev/null +++ b/plugins/aidd-pm/skills/14-roadmap/assets/stakeholder-template.md @@ -0,0 +1,22 @@ +<!-- Stakeholder roadmap template. Fill every angle-bracket placeholder from the team roadmap filtered per audiences; drop a row the audience must not see. Remove this comment. --> +--- +type: roadmap +audience: stakeholders +quarter: <quarter label> +source: <team roadmap path> +updated: <yyyy-mm-dd> +--- + +# Roadmap: <quarter label> + +<What customers and partners gain this quarter, in one or two sentences, with no new claim.> + +```mermaid +<the chart per views, holding only the rows below> +``` + +| Theme | What changes for you | When | Status | +| --- | --- | --- | --- | +| <theme> | <outcome in the audience's words> | <month or horizon> | <committed, planned, exploring, or delivered> | + +<The user's caveat line.> diff --git a/plugins/aidd-pm/skills/14-roadmap/references/audiences.md b/plugins/aidd-pm/skills/14-roadmap/references/audiences.md new file mode 100644 index 000000000..4f8f01e7c --- /dev/null +++ b/plugins/aidd-pm/skills/14-roadmap/references/audiences.md @@ -0,0 +1,17 @@ +# Audiences + +| Element | Team view | Stakeholder view | +| --- | --- | --- | +| Outcome and theme | yes | yes, in the audience's words, with no new claim | +| Placement | month or horizon | the granularity the user picks for this audience | +| Commitment | all levels | `committed` and `planned`; `exploring` only when the user includes it | +| Trace | ticket ids and paths | none | +| Estimates and capacity | yes | none | +| Dependencies and risks | yes | only those the user chooses to share | +| Items the user excludes | yes | none | +| Progress flags | yes | only `done`, shown as `delivered`, on an update | +| Change log | yes | none | + +The stakeholder view never promises more than the team view commits. + +A client or sales audience gets the stakeholder view. Its caveat line is the user's own words. diff --git a/plugins/aidd-pm/skills/14-roadmap/references/handoffs.md b/plugins/aidd-pm/skills/14-roadmap/references/handoffs.md new file mode 100644 index 000000000..21c3d54ff --- /dev/null +++ b/plugins/aidd-pm/skills/14-roadmap/references/handoffs.md @@ -0,0 +1,11 @@ +# Handoffs + +Offer the named capability with what was observed, then stop. Never invoke it silently, never write outside a roadmap. + +| Observed | Capability | Return | +| --- | --- | --- | +| an item with no stated outcome | Epic | the item stays a `proposal` until the Epic exists | +| an opportunity with no framing | Product Brief | the item stays `exploring` until the brief exists | +| a priority the user wants settled by evidence | a decision capability | placement waits for the decision | +| a placed item that needs slicing | User Story | one-way; the roadmap keeps the item | +| no match | none | report what was observed | diff --git a/plugins/aidd-pm/skills/14-roadmap/references/persistence.md b/plugins/aidd-pm/skills/14-roadmap/references/persistence.md new file mode 100644 index 000000000..e7809aefa --- /dev/null +++ b/plugins/aidd-pm/skills/14-roadmap/references/persistence.md @@ -0,0 +1,19 @@ +# Persistence + +| File | Path | +| --- | --- | +| team roadmap | `aidd_docs/product/roadmaps/<quarter-slug>.md` | +| stakeholder view | `aidd_docs/product/roadmaps/<quarter-slug>-stakeholders.md` | + +`<quarter-slug>` is the quarter label in kebab-case, for example `2026-q4` or `fy27-q1`. Several products in one project: prefix it with the product slug. + +| Situation | Result | +| --- | --- | +| explicit target | use it | +| no roadmap for the quarter | create both files | +| a roadmap for the quarter exists | update both in place; never create a second one | +| no target and no `aidd_docs/` | ask session or Markdown | + +Updating keeps the file identity and appends to the change log; a past entry is never rewritten. + +Relation values are project-relative paths or ticket ids. diff --git a/plugins/aidd-pm/skills/14-roadmap/references/placement.md b/plugins/aidd-pm/skills/14-roadmap/references/placement.md new file mode 100644 index 000000000..9d1950a00 --- /dev/null +++ b/plugins/aidd-pm/skills/14-roadmap/references/placement.md @@ -0,0 +1,32 @@ +# Placement + +## Granularity + +| Granularity | Slots | Use when | +| --- | --- | --- | +| month | the three months of the quarter | the team commits to a month | +| horizon | `now`, `next`, `later` inside the quarter | order is known, dates are not | + +The user picks one per roadmap. `later` stays inside the quarter; beyond it is out of scope. + +## Commitment + +| Level | Meaning | +| --- | --- | +| `committed` | the team agreed to deliver it this quarter | +| `planned` | intended, not yet agreed by the team | +| `exploring` | under discovery; delivery is not promised | + +A `proposal` trace does not block a level, and stays visible beside it. + +## Order signals + +| Signal | Effect | +| --- | --- | +| required predecessor | placed no later than its dependent | +| fixed external date a source states | placed no later than that date | +| settled decision | follows the decision record | +| user priority | decides between items no other signal orders | +| unsupported value or urgency | no weight | + +Never manufacture a score. Propose a relative order with the signal behind each position. diff --git a/plugins/aidd-pm/skills/14-roadmap/references/progress.md b/plugins/aidd-pm/skills/14-roadmap/references/progress.md new file mode 100644 index 000000000..ccc5a01b8 --- /dev/null +++ b/plugins/aidd-pm/skills/14-roadmap/references/progress.md @@ -0,0 +1,17 @@ +# Progress + +Flags compare the placement with the source status read today. + +| Flag | Month granularity | Horizon granularity | +| --- | --- | --- | +| `done` | the source status is done | the source status is done | +| `on track` | started, and its month has not ended | a `now` item in progress | +| `at risk` | its month is current and the source is not started, or a predecessor is not done | a `now` item not started, or a predecessor not done | +| `slipped` | its month has ended and the source is not done | the quarter has ended and the source is not done | +| `dropped` | the source is cancelled or superseded | the source is cancelled or superseded | +| `unplanned` | a source item in scope that is absent from the roadmap | same | +| `untraced` | a `proposal` item; no status can be read | same | + +Read status only from the source. Closed children never make an Epic done. + +A ticket status maps to done, started, or not started by the tool's own workflow categories. An unmapped status is reported as read, with no flag. diff --git a/plugins/aidd-pm/skills/14-roadmap/references/sources.md b/plugins/aidd-pm/skills/14-roadmap/references/sources.md new file mode 100644 index 000000000..47e7989b4 --- /dev/null +++ b/plugins/aidd-pm/skills/14-roadmap/references/sources.md @@ -0,0 +1,17 @@ +# Sources + +Use each source only for what it states. + +| Source | Where | Yields | Trace | +| --- | --- | --- | --- | +| Epic | `aidd_docs/backlog/epics/*.md`, or the configured backlog | outcome, status, `estimate`, `depends_on`, `order` | the Epic path or id | +| Product Brief | `aidd_docs/product/*.md` with `revision: current` | objective and the opportunity it frames | the brief path | +| Ticket | the configured ticketing tool | title, status, estimate, due date, parent | the ticket id | +| Decision record | a decision log the project keeps in `aidd_docs/` or its memory | a settled choice and its date | the record path | +| Conversation | the user | intent, priority, placement, commitment | `proposal` until a source exists | + +Resolve the ticketing tool from project memory first, then repo configuration, then environment. No tool configured: skip tickets and say so. + +A superseded or cancelled source yields no candidate. + +Several sources describe one outcome: keep one item and list every trace. diff --git a/plugins/aidd-pm/skills/14-roadmap/references/views.md b/plugins/aidd-pm/skills/14-roadmap/references/views.md new file mode 100644 index 000000000..313723277 --- /dev/null +++ b/plugins/aidd-pm/skills/14-roadmap/references/views.md @@ -0,0 +1,16 @@ +# Views + +Syntax, naming, and tags follow the Mermaid diagram capability's conventions when it is installed. This file owns only what the roadmap puts in the chart. + +| Granularity | Chart | Section | Entry | +| --- | --- | --- | --- | +| month | `gantt` | one per theme | one bar per item, from the first to the last day of its month | +| horizon | `timeline` | one per horizon: `Now`, `Next`, `Later` | one entry per theme, listing its items | + +- Title the chart with the quarter label in a `---` frontmatter block. +- A bar spans only months the user placed; the month bounds are the only dates the chart derives. +- A milestone appears only for a date a source or the user states, tagged `milestone`. +- Tag `done`, `active`, or `crit` only from a progress flag or a user request. +- The stakeholder chart holds only the items its table holds. +- Every chart has a matching table below it; the table is the source of truth. +- Keep labels short and on one line; the table carries the detail. diff --git a/scripts/__tests__/architecture-rules.test.js b/scripts/__tests__/architecture-rules.test.js index 9eb7df1b8..53bb9b6cb 100644 --- a/scripts/__tests__/architecture-rules.test.js +++ b/scripts/__tests__/architecture-rules.test.js @@ -229,7 +229,7 @@ test("sweeping the repository's own plugins/ tree yields zero violations", () => assert.deepEqual(violations, []); // A sweep that never actually exercised a skill with action files would pass the same way — // this pins the sweep to the measured count so it cannot go vacuously green. - assert.equal(skillsWithActions, 48); + assert.equal(skillsWithActions, 52); }); test("a table that declares no action column cites nothing, whatever its cells read", () => {