From 41f0a1f680770aedcf351956f9f93775ce7afe87 Mon Sep 17 00:00:00 2001 From: Yordis Prieto Date: Tue, 26 May 2026 15:51:57 -0400 Subject: [PATCH 1/2] feat(product-requirements): introduce PRD and FRD authoring skills Authors and reviewers need consistent structure for product-level context and feature-level requirements so engineering can pick up work without losing intent. Signed-off-by: Yordis Prieto --- .claude-plugin/marketplace.json | 6 + .github/release-please-config.json | 3 + .github/release-please-manifest.json | 3 +- .../.claude-plugin/plugin.json | 9 + .../README.md | 76 +++++++ .../skills/frd-getting-started/SKILL.md | 178 +++++++++++++++ .../skills/frd-review/SKILL.md | 185 +++++++++++++++ .../skills/frd-split/SKILL.md | 209 +++++++++++++++++ .../skills/frd-write/SKILL.md | 212 ++++++++++++++++++ .../skills/frd-write/assets/frd-template.md | 37 +++ .../skills/prd-business-problem/SKILL.md | 155 +++++++++++++ .../assets/business-problem-template.md | 16 ++ .../skills/prd-current-state/SKILL.md | 131 +++++++++++ .../assets/current-state-template.md | 23 ++ .../skills/prd-custom-overview/SKILL.md | 144 ++++++++++++ .../assets/custom-overview-template.md | 32 +++ .../skills/prd-getting-started/SKILL.md | 137 +++++++++++ .../skills/prd-personas/SKILL.md | 135 +++++++++++ .../prd-personas/assets/personas-template.md | 21 ++ .../skills/prd-product-description/SKILL.md | 160 +++++++++++++ .../assets/product-description-template.md | 27 +++ .../skills/prd-review/SKILL.md | 210 +++++++++++++++++ .../skills/prd-success-metrics/SKILL.md | 164 ++++++++++++++ .../assets/success-metrics-template.md | 30 +++ .../prd-technical-requirements/SKILL.md | 204 +++++++++++++++++ .../assets/technical-requirements-template.md | 65 ++++++ .../requirements-operating-model/SKILL.md | 196 ++++++++++++++++ 27 files changed, 2767 insertions(+), 1 deletion(-) create mode 100644 plugins/trogonstack-product-requirements/.claude-plugin/plugin.json create mode 100644 plugins/trogonstack-product-requirements/README.md create mode 100644 plugins/trogonstack-product-requirements/skills/frd-getting-started/SKILL.md create mode 100644 plugins/trogonstack-product-requirements/skills/frd-review/SKILL.md create mode 100644 plugins/trogonstack-product-requirements/skills/frd-split/SKILL.md create mode 100644 plugins/trogonstack-product-requirements/skills/frd-write/SKILL.md create mode 100644 plugins/trogonstack-product-requirements/skills/frd-write/assets/frd-template.md create mode 100644 plugins/trogonstack-product-requirements/skills/prd-business-problem/SKILL.md create mode 100644 plugins/trogonstack-product-requirements/skills/prd-business-problem/assets/business-problem-template.md create mode 100644 plugins/trogonstack-product-requirements/skills/prd-current-state/SKILL.md create mode 100644 plugins/trogonstack-product-requirements/skills/prd-current-state/assets/current-state-template.md create mode 100644 plugins/trogonstack-product-requirements/skills/prd-custom-overview/SKILL.md create mode 100644 plugins/trogonstack-product-requirements/skills/prd-custom-overview/assets/custom-overview-template.md create mode 100644 plugins/trogonstack-product-requirements/skills/prd-getting-started/SKILL.md create mode 100644 plugins/trogonstack-product-requirements/skills/prd-personas/SKILL.md create mode 100644 plugins/trogonstack-product-requirements/skills/prd-personas/assets/personas-template.md create mode 100644 plugins/trogonstack-product-requirements/skills/prd-product-description/SKILL.md create mode 100644 plugins/trogonstack-product-requirements/skills/prd-product-description/assets/product-description-template.md create mode 100644 plugins/trogonstack-product-requirements/skills/prd-review/SKILL.md create mode 100644 plugins/trogonstack-product-requirements/skills/prd-success-metrics/SKILL.md create mode 100644 plugins/trogonstack-product-requirements/skills/prd-success-metrics/assets/success-metrics-template.md create mode 100644 plugins/trogonstack-product-requirements/skills/prd-technical-requirements/SKILL.md create mode 100644 plugins/trogonstack-product-requirements/skills/prd-technical-requirements/assets/technical-requirements-template.md create mode 100644 plugins/trogonstack-product-requirements/skills/requirements-operating-model/SKILL.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 79c0b93..ae8bfd5 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -54,6 +54,12 @@ "description": "Event-driven architecture skills for designing event names, schemas, contracts, and catalogs following good practices for domain and integration events", "source": "./plugins/trogonstack-eda", "category": "development" + }, + { + "name": "trogonstack-product-requirements", + "description": "Skills for writing and reviewing Product Requirements Documents (PRDs) and Feature Requirements Documents (FRDs)", + "source": "./plugins/trogonstack-product-requirements", + "category": "development" } ] } diff --git a/.github/release-please-config.json b/.github/release-please-config.json index 68d912e..49baf1a 100644 --- a/.github/release-please-config.json +++ b/.github/release-please-config.json @@ -47,6 +47,9 @@ }, "plugins/trogonstack-eda": { "component": "trogonstack-eda" + }, + "plugins/trogonstack-product-requirements": { + "component": "trogonstack-product-requirements" } }, "plugins": [ diff --git a/.github/release-please-manifest.json b/.github/release-please-manifest.json index b3afdfb..4961295 100644 --- a/.github/release-please-manifest.json +++ b/.github/release-please-manifest.json @@ -6,5 +6,6 @@ "plugins/trogonstack-ask": "0.1.2", "plugins/trogonstack-otel": "0.1.1", "plugins/trogonstack-eventmodeling": "0.1.1", - "plugins/trogonstack-eda": "0.1.1" + "plugins/trogonstack-eda": "0.1.1", + "plugins/trogonstack-product-requirements": "0.0.1" } diff --git a/plugins/trogonstack-product-requirements/.claude-plugin/plugin.json b/plugins/trogonstack-product-requirements/.claude-plugin/plugin.json new file mode 100644 index 0000000..e152d51 --- /dev/null +++ b/plugins/trogonstack-product-requirements/.claude-plugin/plugin.json @@ -0,0 +1,9 @@ +{ + "name": "trogonstack-product-requirements", + "description": "Skills for writing and reviewing Product Requirements Documents (PRDs)", + "version": "0.0.1", + "author": { + "name": "TrogonStack", + "url": "https://github.com/TrogonStack" + } +} diff --git a/plugins/trogonstack-product-requirements/README.md b/plugins/trogonstack-product-requirements/README.md new file mode 100644 index 0000000..ab6d5ad --- /dev/null +++ b/plugins/trogonstack-product-requirements/README.md @@ -0,0 +1,76 @@ +# Product Requirements + +Skills for writing and reviewing product-level and feature-level requirements. All artifacts live under `.trogonai/project/{projectid}/`. + +## Requirements Operating Model + +These skills operate on the Requirements side of the product development flow: + +- **Requirements** own product-level context, feature requirements, and the feature hierarchy. +- **Blueprints** own high-level architecture, runtime design, and code links. +- **Work Orders** own implementable delivery slices and planning phases. + +Shared behavior for module boundaries, source-of-truth checks, clarification, feature hierarchy, and downstream impact lives in the `requirements-operating-model` skill. When the TrogonStack `ask-question` skill is available, use it for clarification sessions; these skills keep the Product Requirements-specific judgment about what needs to be clarified. + +| Skill | Purpose | +|-------|---------| +| `requirements-operating-model` | Shared Requirements-module boundaries, clarification pattern, source-of-truth rules, feature hierarchy, and downstream-impact guidance | + +## Product Overview Documents + +Product Overview Documents capture the high-level **why** and **what** for the entire product. + +- The **why** is the business motivation: the problems being solved, the KPIs not being met, the North Star goals the business is pursuing. +- The **what** is the product description: what the product is and how its parts fit together. + +These documents give anyone (executive, product manager, or engineer) the context they need before looking at specific features. + +The six default files live under `.trogonai/project/{projectid}/prd/`: + +| Concern | Skill | File | +|---------|-------|------| +| Why: problems being solved | `prd-business-problem` | `business-problem.prd.md` | +| Why: status quo being improved | `prd-current-state` | `current-state.prd.md` | +| Why: who it serves and what success means for them | `prd-personas` | `personas.prd.md` | +| What: the product and how its parts fit together | `prd-product-description` | `product-description.prd.md` | +| Why: the KPIs / North Star being pursued | `prd-success-metrics` | `success-metrics.prd.md` | +| What: the technical constraints the product must meet | `prd-technical-requirements` | `technical-requirements.prd.md` | +| Custom: product-level context beyond the defaults | `prd-custom-overview` | `{slug}.prd.md` | +| Audit of all of the above | `prd-review` | `review.prd.md` | + +Each section skill has a focused document owner, but the set is not isolated. Later documents should read the earlier context they depend on, and reviews should flag source-of-truth conflicts across the set. + +Additional Product Overview Documents are created with `prd-custom-overview` when the six defaults do not cover a product-specific context area. Custom documents still explain product-level **why** or **what** in plain language; they must name their relationship to the defaults or other custom overviews so they do not become miscellaneous buckets. Feature behavior belongs in FRDs. + +## Feature Requirements Documents + +Feature Requirements Documents (FRDs) capture the localized **why** and **what** for a single feature: what engineers actually pick up to build. + +- The **why** is the user story: *"As a \, I want to \, so that I can \."* +- The **what** is the acceptance criteria: *"When \, the system shall/should/may \."* + +Each FRD follows the same three-section template (**Overview**, **Terminology**, **Requirements**) with stable IDs so they can be referenced unambiguously from code, commits, tickets, tests, and reviews. Cross-requirement behavior should usually be captured as acceptance criteria; `Child FRDs` is the standard built-in extension for parent documents with nested children. + +- **`REQ-`** = **Requirement**: one cohesive, independently testable capability. Format: `REQ-[PREFIX]-NNN`. +- **`AC-`** = **Acceptance Criterion**: one observable behavior the system must exhibit. Format: `AC-[PREFIX]-NNN.N`, where `NNN` matches the parent requirement. + +Large features nest as parent + children, where the parent delivers value on its own and the child is meaningless without the parent. + +Files live under `.trogonai/project/{projectid}/frd/`: + +- Top-level: `{slug}.frd.md` +- Parent with children: `{parent-slug}/index.frd.md` + `{parent-slug}/{child-slug}.frd.md` + +| Skill | Purpose | +|-------|---------| +| `frd-getting-started` | Produce the initial set of FRDs for a new project, calibrated agile vs waterfall | +| `frd-write` | Author or refine a single FRD | +| `frd-split` | Split, merge, or nest FRDs using the parent-delivers-value rule | +| `frd-review` | Audit a single FRD or a tree of FRDs | + +## Installation + +```bash +claude plugin marketplace add TrogonStack/agentskills +claude plugin install trogonstack-product-requirements@TrogonStack +``` diff --git a/plugins/trogonstack-product-requirements/skills/frd-getting-started/SKILL.md b/plugins/trogonstack-product-requirements/skills/frd-getting-started/SKILL.md new file mode 100644 index 0000000..5939106 --- /dev/null +++ b/plugins/trogonstack-product-requirements/skills/frd-getting-started/SKILL.md @@ -0,0 +1,178 @@ +--- +name: frd-getting-started +description: Produce the initial set of Feature Requirements Documents (FRDs) for a new project. Calibrates between an agile first pass (small set of must-have features only) and a waterfall first pass (comprehensive coverage). Asks how many features to draft, identifies them from the project's product overview, and scaffolds each via the FRD template. Use when the user is starting a project and there are no FRDs yet. +allowed-tools: + - AskUserQuestion + - Read + - Write + - Glob + - Grep +--- + +# FRD Getting Started: Initial Feature Set + +## Purpose + +Projects are not seeded with any default FRDs. This skill walks the user through producing the **initial set** of FRDs once, calibrated to how the user wants to work. + +## Shared Operating Model + +Use `requirements-operating-model` before translating Product Overview Documents into FRDs. Use its clarification pattern for ambiguous feature boundaries, and follow its source-of-truth and downstream-impact rules. + +## When to Use + +- A project has been created and `.trogonai/project/{projectid}/frd/` is empty +- The user wants to plan a chunk of features in one pass rather than drafting them ad-hoc +- The user has just produced the Product Overview Documents (`prd-*` files) and wants to translate them into the first FRDs + +## Resolve Project + +1. Determine `projectid` (ask if not supplied; offer choices via `Glob`). +2. `Glob` `.trogonai/project/{projectid}/frd/**/*.frd.md`: if any FRDs already exist, stop and direct the user to `frd-write`. This skill is for getting started only, not for extending an established set. +3. Read whichever of these files exist for context, in priority order: + - `personas.prd.md` (roles for user stories) + - `product-description.prd.md` (the surfaces and components to translate into features) + - `business-problem.prd.md`, `success-metrics.prd.md` (to prioritize) + - `current-state.prd.md`, `technical-requirements.prd.md` (to catch status-quo scope and constraints) + +If the Product Overview is missing, surface that as a finding and ask whether to proceed or run the relevant `prd-*` skills first. + +## Calibrate the Pass + +Ask the user how they want to work this first time. Offer two anchors and let them pick or land somewhere in between: + +- **Agile first pass**: draft only the **2–4 must-have features** that prove the product can deliver its primary outcome metric. Other features are deferred to later passes. +- **Waterfall first pass**: draft **every feature visible in the Product Description** before any one is built, so engineering can plan and estimate the whole scope. + +Then ask: + +- Approximate number of FRDs for this pass (the calibration sets a default; the user can override). +- Whether sub-features should be drafted now, or deferred until the parent is built (`frd-split` can do this later). + +## Identify the Feature Set + +Use the Product Description's components and surfaces as the candidate list. For each candidate, ask: + +- Does this pass the **feature unit** definition: one cohesive, independently-buildable capability with a clear user-facing value? +- Is it top-level, or a child of another candidate? Apply the parent-delivers-value rule: parents must work without the child; children must be meaningless without the parent. + +Group candidates into: + +- **This pass** (in-scope for getting started) +- **Later passes** (deferred) +- **Not a feature** (cross-cutting concerns, non-functional requirements: these belong in `technical-requirements.prd.md`) + +Read the grouping back to the user and get explicit confirmation before scaffolding. + +## Scaffold the FRDs + +For each feature in **this pass**, scaffold a file at: + +- Top-level → `.trogonai/project/{projectid}/frd/{slug}.frd.md` +- Child → if the initial pass includes children, write the parent directly as `{parent}/index.frd.md` and write children as `{parent}/{slug}.frd.md` + +Each scaffold is a **stub**, not a finished FRD. It contains: + +- Title, project, prefix, parent reference, status `Stub`, last-updated. +- A placeholder Overview noting what the feature is meant to cover (one sentence, taken from the Product Description). +- An empty Terminology section. +- A placeholder requirement `REQ-{PREFIX}-001: ` with no acceptance criteria, marked `Status: pending`. + +After scaffolding, list the files and recommend the user run `frd-write` per feature to fill in the actual requirements. Do **not** try to fully author every FRD here; that loses the per-feature discovery quality. + +### Prefix assignment + +For each top-level scaffold, ask the user to confirm a 2–4 letter prefix derived from the feature name. `Grep` existing files in the project to ensure uniqueness. For children, the prefix is `{parent-prefix}-{sub}` per the standard rule. + +## Stub Template + +```markdown +# + +- **Project:** {projectid} +- **Prefix:** {PREFIX} +- **Parent FRD:** +- **Status:** Stub +- **Last updated:** + +## Overview + + + +## Terminology + + + +## Requirements + +### REQ-{PREFIX}-001: + +**Status:** pending + +**User Story:** + +**Acceptance Criteria:** +- + +``` + +The canonical shape comes from the project's Feature Requirements Template when available. Otherwise, use the bundled default at `../frd-write/assets/frd-template.md`. The stub above is the abbreviated form for scaffolding; `frd-write` expands it into the full template. + +## Output Summary + +After scaffolding, write `.trogonai/project/{projectid}/frd/_getting-started.md` summarizing the pass: + +```markdown +# Getting Started: Initial FRD Set + +- **Project:** {projectid} +- **Date:** +- **Pass style:** +- **Features in this pass:** +- **Features deferred:** + +## This Pass +- [{slug}](./{slug}.frd.md): +- [{parent-slug}/{child-slug}](./{parent-slug}/{child-slug}.frd.md): + +## Deferred to Later Passes +- : + +## Not a Feature (re-homed elsewhere) +- : belongs in + +## Next Steps +1. Run `frd-write` per stub to author the full FRD. +2. Run `frd-review` once a meaningful chunk is authored. +3. Run `frd-split` if a feature grows beyond ~5 requirements. +``` + +## Quality Bar + +The pass is complete when: + +- Every feature in this pass has a stub file with prefix, parent reference, and a placeholder REQ-001. +- Parents and children follow the parent-delivers-value rule. +- A summary file enumerates the pass, deferrals, and non-features. +- The user has explicit next steps (which `frd-write` calls come next). + +## Anti-Patterns to Reject + +- Trying to fully author every FRD in one pass; that bypasses per-feature discovery. +- Scaffolding "every component" without applying the feature-unit definition. +- Scaffolding sub-features whose parents have not been scaffolded. +- Re-running this skill against a project that already has FRDs; use `frd-write` instead. + +## Related Skills + +- `frd-write`: author the full content of each scaffolded FRD +- `frd-split`: decompose a feature that turns out to be an umbrella +- `frd-review`: audit once a pass of authoring is done +- `prd-product-description`: re-check if the candidate feature list reveals product-shape gaps + +## Allowed Tools + +- **AskUserQuestion**: drive calibration and feature grouping +- **Read**: load Product Overview files for context +- **Write**: scaffold stub FRDs and the getting-started summary +- **Glob**: verify the project is empty of FRDs and list candidates diff --git a/plugins/trogonstack-product-requirements/skills/frd-review/SKILL.md b/plugins/trogonstack-product-requirements/skills/frd-review/SKILL.md new file mode 100644 index 0000000..5388f72 --- /dev/null +++ b/plugins/trogonstack-product-requirements/skills/frd-review/SKILL.md @@ -0,0 +1,185 @@ +--- +name: frd-review +description: Review Feature Requirements Documents (FRDs) (single file or full tree) against the Overview / Terminology / Requirements template, source-of-truth rules, module boundaries, downstream impact, and the parent-delivers-value rule for sub-features. Writes a review file. Use when the user asks to review, audit, or sanity-check a feature spec. +allowed-tools: + - AskUserQuestion + - Read + - Write + - Glob + - Grep +--- + +# FRD: Review a Feature Requirements Document + +## Purpose + +Audit an FRD (or a parent + its nested children) the way an experienced engineer or product lead would in planning: surface the gaps that cause estimation churn, rework after implementation, or bugs found in QA. + +## Shared Operating Model + +Use `requirements-operating-model` before reviewing. Use it to check module boundaries, source-of-truth conflicts, feature hierarchy, and downstream Blueprint / Work Order impact. + +## When to Use + +- An FRD draft needs a sanity check before engineering picks it up +- A parent FRD with children needs to be audited as a tree +- A reviewer wants a second pass on someone else's feature spec + +## Resolve the Target + +1. Determine `projectid` (ask if not supplied; offer choices via `Glob`). +2. Resolve what to review: + - A specific FRD path → review just that file. + - A directory (parent with children) → review the parent's `index.frd.md` plus every `*.frd.md` sibling. + - "Everything under this project" → glob `.trogonai/project/{projectid}/frd/**/*.frd.md`. +3. If `personas.prd.md` exists in the project, read it: user stories should reference its personas. + +## Per-FRD Checklist + +For each FRD, run every item and mark **Pass**, **Gap**, **Risk**, or **N/A** with a one-line justification. + +### 1. Overview +- [ ] One or two narrative paragraphs (not a bullet list) +- [ ] Describes what the feature does and why users need it +- [ ] Focuses on problem solved and value delivered, not implementation mechanisms +- [ ] A stakeholder could understand the feature in under a minute + +### 2. Terminology +- [ ] Only feature-specific terms are defined +- [ ] No industry-standard or obvious terms (e.g., "API", "user") are defined +- [ ] Definitions are brief and precise +- [ ] If absent, the absence is justified (no ambiguous terms exist) + +### 3. Requirements: structure +- [ ] Each requirement uses the id format `REQ-{PREFIX}-NNN: Title` +- [ ] Prefix matches the FRD's declared prefix (and parent-prefix-{sub} for children) +- [ ] Sequence numbers are zero-padded to three digits and unique within the file +- [ ] Each requirement has a single-sentence user story in `As a [role], I want to [action], so that I can [outcome].` form +- [ ] Role is a concrete persona (and matches `personas.prd.md` if present) +- [ ] At least one acceptance criterion per requirement + +### 4. Acceptance Criteria: content +- [ ] Each AC uses id format `AC-{PREFIX}-NNN.N` matching its requirement +- [ ] Each AC begins with `When [condition],` followed by `the system shall/should/may [behavior].` +- [ ] Modal verbs are correctly used: **shall** = mandatory, **should** = recommended, **may** = optional +- [ ] Each AC is atomic (one behavior, not compound) +- [ ] Each AC is testable: clear enough to write a test against +- [ ] Each requirement has at least one happy-path AC and at least one failure / edge-case AC + +### 5. Optional Extension Sections +- [ ] `Child FRDs`, if present, matches the actual child files and summarizes their user-facing enhancement +- [ ] Any other extension section is defined by the project's Feature Requirements Template +- [ ] Extension sections do not prescribe UI, screens, user flows, or implementation details +- [ ] Cross-requirement behavior is captured as acceptance criteria whenever possible +- [ ] Empty or placeholder extension sections are absent + +### 6. Cross-cutting hygiene +- [ ] Project, prefix, parent reference, status, last-updated present +- [ ] Parent reference (if any) points to a file that exists +- [ ] No "TBD" left unowned +- [ ] Adjective-only behaviors ("appropriately", "correctly", "smoothly", "fast") flagged + +## Cross-FRD Checks (parent + children) + +When reviewing a tree: + +- [ ] Every child's requirements describe an enhancement, not a dependency the parent needs to function +- [ ] **Parent-delivers-value rule:** removing any child file would leave the parent still passing the feature-unit definition +- [ ] **Child-meaningless-without-parent rule:** each child only makes sense as part of the parent's scope +- [ ] Child prefixes are `{parent-prefix}-{sub}` and the sub-prefix is unique among siblings +- [ ] No requirement id collides anywhere in the tree +- [ ] Parent's `## Child FRDs` list matches the actual files on disk +- [ ] No "misc" or "other" child (suggests the split axis was wrong) +- [ ] Personas referenced across siblings are consistent with `personas.prd.md` + +## Operating Model Checks + +- [ ] Feature requirements do not contain Blueprint-owned architecture or Work Order-owned delivery tasks +- [ ] FRD user stories and ACs can be traced to Product Overview context or explicit user input +- [ ] Requirement changes likely to affect Blueprints or Work Orders are called out for downstream follow-up +- [ ] Open questions use the shared clarification pattern when they block engineering readiness + +## Output + +Write the review to: + +- Single FRD: `.trogonai/project/{projectid}/frd/{slug}.review.md` +- Tree: `.trogonai/project/{projectid}/frd/{parent-slug}/_review.md` +- Whole project: `.trogonai/project/{projectid}/frd/_review.md` + +Template: + +```markdown +# FRD Review + +- **Project:** {projectid} +- **Scope:** +- **Reviewed:** +- **Overall verdict:** + +## Top Findings +1. +2. +3. + +## Per-FRD Results + +### +- Overview: Pass / Gap: +- Terminology: Pass / Gap: +- Requirements structure: Pass / Gap: +- Acceptance criteria: Pass / Gap: +- Optional extension sections: Pass / Gap / N/A: +- Hygiene: Pass / Gap: + + + +## Cross-FRD Findings (if tree) +- Parent-delivers-value rule: Pass / Gap: +- Child-meaningless-without-parent rule: Pass / Gap: +- ID collisions: +- Child FRDs list consistency: Pass / Gap + +## Operating Model and Downstream Impact +- Source of truth: Pass / Gap / Risk: +- Module boundaries: Pass / Gap / Risk: +- Likely downstream follow-up: + +## Required Revisions (blockers) +- : fix with `frd-write` or `frd-split` + +## Recommended Revisions (non-blockers) +- : fix with `` + +## Suggested Questions for the Author +- +``` + +If a previous review file exists at the same path, overwrite it. + +## Verdict Rubric + +- **Ready**: no gaps in Requirements structure or Acceptance Criteria; overview clear; optional extension sections are either useful or absent; sub-feature rules satisfied. Minor wording only. +- **Ready with revisions**: gaps exist but fix path is clear. For each gap, name the section / requirement and the skill (`frd-write` or `frd-split`) that fixes it. +- **Not ready**: user stories are generic ("As a user, I want X"), ACs are untestable ("handled appropriately"), or sub-features violate the parent-value rules. Engineering cannot estimate or build from this as-is. + +## Key Principles + +- **Surface gaps, do not rewrite.** Point to what is missing and why it matters. +- **Cite the id.** Every finding references the specific `REQ-...` or `AC-...` it came from. +- **Distinguish blockers from polish.** Required vs recommended must be obvious. +- **Recommend the fix path.** Each gap maps to `frd-write` (refine) or `frd-split` (restructure). + +## Related Skills + +- `frd-write`: author or refine a single FRD +- `frd-split`: restructure FRDs by splitting, merging, or nesting +- `frd-getting-started`: produce the initial set of FRDs +- `prd-review`: companion overview-level review + +## Allowed Tools + +- **AskUserQuestion**: resolve project and target if not supplied +- **Read**: load each FRD and the project's personas +- **Write**: write the review file +- **Glob / Grep**: locate FRDs, detect adjective-only ACs, check id collisions diff --git a/plugins/trogonstack-product-requirements/skills/frd-split/SKILL.md b/plugins/trogonstack-product-requirements/skills/frd-split/SKILL.md new file mode 100644 index 0000000..337a2b5 --- /dev/null +++ b/plugins/trogonstack-product-requirements/skills/frd-split/SKILL.md @@ -0,0 +1,209 @@ +--- +name: frd-split +description: Split, merge, or nest Feature Requirements Documents (FRDs) using the parent-delivers-value rule where a parent feature must deliver value on its own and a child must be meaningless without the parent. Promotes parent files into directories, scaffolds child FRDs with appended prefixes, and rewrites the parent into an umbrella. Use when an FRD has grown too large or when multiple FRDs should be combined. +allowed-tools: + - AskUserQuestion + - Read + - Write + - Edit + - Glob + - Grep + - Bash(rm:*) +--- + +# FRD: Split, Merge, or Nest Features + +## Purpose + +Restructure FRDs so each one passes the **feature unit** test: it delivers cohesive value, has a single owner, and can be planned independently. + +## Shared Operating Model + +Use `requirements-operating-model` before restructuring. This skill changes the feature hierarchy, so apply the source-of-truth, clarification, and downstream-impact rules before writing files. + +## The Decision Rule + +Apply these three options strictly: + +- **Split into separate top-level features** when each resulting piece passes the feature unit definition on its own, or when different roles own different parts. +- **Merge / keep in one feature** when the pieces' requirements break without each other, they complete one task together, or they are describable in one sentence. +- **Nest as a child feature** when the parent already delivers value on its own, the child enhances but is not required, and the child is meaningless without the parent. + +> Example: "Search" finds items by keyword: complete on its own. "Search Filters" adds faceted filtering. Search works without filters; filters need search. → **Nest** Search Filters under Search. + +If a candidate child *would break the parent if removed*, it is not a child. It is part of the parent (merge), or it is its own top-level feature (split). + +## When to Use + +- An FRD has more than roughly 5–7 requirements +- A reviewer flagged an FRD as overscoped +- Two FRDs duplicate or depend on each other and should be reconciled +- A feature is naturally an umbrella with optional enhancements (e.g., User Management with User Roles, Groups, Audit Log) + +## Resolve Project and Targets + +1. Determine `projectid` (ask if not supplied; offer choices via `Glob`). +2. Identify the FRD(s) to restructure. If a single FRD is being split, locate it via `Glob`. If multiple FRDs are being reconciled, list them all. +3. Read every target file in full before proposing changes: no requirement may be dropped silently. + +## Discovery + +### 1. Decide the operation + +Ask the user, given the targets, which operation applies. Use the decision rule above; do not let the user pick "nest" for something that violates the parent-delivers-value test. + +### 2. For a SPLIT or NEST: identify each resulting feature + +For each new child or split-out feature: + +- **Slug**: kebab-case, scoped to the parent if a child (e.g., parent `user-management` → child `user-roles`). +- **Sub-prefix** (children only): 2–3 letters appended to the parent's prefix. Confirm uniqueness against siblings (`Grep` existing FRDs for `REQ-{parent-prefix}-{sub}-`). +- **One-line summary**. +- **Which parent requirements move here**: every existing `REQ-...` in the parent must be assigned to exactly one resulting feature, or explicitly retained in the umbrella. No requirement is dropped. +- **Parent-value check** (children only): confirm the parent still passes feature-unit alone after this child is removed. + +Reject: +- "Misc" / "other" children; that means the split axis was wrong. +- Children that share requirements: pick one owner per requirement. +- Children whose absence would break the parent: those are merges or top-level splits, not children. + +### 3. For a MERGE: confirm coherence + +Ask: *"In one sentence, what does the merged feature do?"* If the user cannot, the merge is wrong. Identify requirements to drop as duplicates, requirements to combine, and the new prefix (typically the dominant feature's prefix). + +### 4. Confirm coverage + +Before writing, read back every requirement and where it lands. Get explicit confirmation. + +## File Layout + +After a SPLIT or NEST under a parent: + +``` +.trogonai/project/{projectid}/frd/{parent-slug}/ +├── index.frd.md +├── {child-1-slug}.frd.md +├── {child-2-slug}.frd.md +└── ... +``` + +If the parent was at `frd/{parent-slug}.frd.md`, read it, write to `frd/{parent-slug}/index.frd.md`, then remove the original file with `rm` only after every child file has been written successfully. + +After a SPLIT into top-level peers: each resulting feature is its own `frd/{slug}.frd.md`. The original file is replaced (its requirements have moved out). + +After a MERGE: write the merged file at the surviving slug; remove absorbed files with `rm` only after the merged file is successfully written. + +## Output: Child FRD + +```markdown +# + +- **Project:** {projectid} +- **Prefix:** {PARENT-PREFIX}-{SUB} +- **Parent FRD:** ./index.frd.md +- **Status:** Draft +- **Last updated:** + +## Overview + +<1–2 paragraphs scoped to this child: what enhancement it adds, why it matters, the parent it builds on> + +## Terminology + +- **:** + +## Requirements + +### REQ-{PARENT-PREFIX}-{SUB}-001: +**User Story:** As a , I want to , so that I can . + +**Acceptance Criteria:** +- AC-{PARENT-PREFIX}-{SUB}-001.1: When , the system shall . + + +``` + +When moving requirements from parent to child, renumber under the child's prefix starting at `001`. Preserve the original AC text verbatim: only the IDs change. If the source FRD has extension content, move it only when it is defined by the project's template or convert the relevant behavior into acceptance criteria owned by the resulting feature. + +## Output: Parent Umbrella (after a NEST) + +Rewrite parent `index.frd.md` so that: + +- Overview is unchanged or lightly edited to acknowledge the children. +- Terminology stays with the parent only if the terms apply project-wide; otherwise move term entries down to the children they belong to. +- Requirements that remain on the parent are only those that describe the umbrella value (the parent-delivers-value-on-its-own behaviors). Requirements that move to a child are listed at the child instead. +- A new `## Child FRDs` section enumerates the children with one-line summaries. +- Extension sections remain only if the project's template defines them and the content still applies to the parent's remaining requirements or parent/child boundaries. + +```markdown +# + +- **Project:** {projectid} +- **Prefix:** {PARENT-PREFIX} +- **Parent FRD:** +- **Status:** Draft +- **Last updated:** + +## Overview + + + +## Terminology + +- + +## Requirements + + + +## Child FRDs + +- [{child-1-slug}](./{child-1-slug}.frd.md): +- [{child-2-slug}](./{child-2-slug}.frd.md): +``` + +## Quality Bar + +The restructure is complete when: + +- Every original requirement is accounted for: none dropped silently. +- The parent (after a nest) still passes the feature-unit definition on its own. +- Every child fails the feature-unit definition without the parent (that is the point). +- No "misc" or "other" child exists. +- IDs are renumbered correctly under their owning feature's prefix; no duplicate IDs across the project. +- Likely downstream Blueprint or Work Order follow-up is identified by human-readable name when the split changes feature boundaries, requirement IDs, or acceptance criteria. + +## Anti-Patterns to Reject + +- Splitting by implementation layer ("frontend" vs "backend") instead of user-facing capability. +- Leaving the parent both as an umbrella *and* with its own deep requirements; pick one role per requirement. +- Calling something a child when removing it would break the parent. +- Renaming the parent without keeping the original prefix stable when only children are being added (breaks existing IDs). + +## Worked Example + +**Parent:** User Management: admins can create, view, edit, deactivate users and reset passwords. Delivers value alone. + +**Children (correctly nested: parent works without them, they are meaningless without it):** + +- User Roles: assign roles for access control +- User Groups: bulk operations on user sets +- User Audit Log: change tracking for compliance + +If, instead, "Login" had been proposed as a child of User Management, reject it: User Management cannot function without authentication, so Login is not a child. + +## Related Skills + +- `frd-write`: author a new child or top-level FRD +- `frd-review`: audit the parent + children after splitting +- `prd-product-description`: re-check the product-level boundaries after major restructures + +## Allowed Tools + +- **AskUserQuestion**: drive the operation choice and confirm coverage +- **Read**: load every target FRD before changing anything +- **Write**: create new files and rewrite the parent umbrella +- **Edit**: update Child FRDs lists and surgical sections +- **Glob**: locate existing FRDs +- **Grep**: confirm prefix uniqueness and ID collisions +- **Bash(rm:*)**: remove superseded files only after replacement files are written diff --git a/plugins/trogonstack-product-requirements/skills/frd-write/SKILL.md b/plugins/trogonstack-product-requirements/skills/frd-write/SKILL.md new file mode 100644 index 0000000..f93cfb3 --- /dev/null +++ b/plugins/trogonstack-product-requirements/skills/frd-write/SKILL.md @@ -0,0 +1,212 @@ +--- +name: frd-write +description: Draft a Feature Requirements Document (FRD) using the Overview / Terminology / Requirements template, Product Overview context, source-of-truth checks, and REQ-[PREFIX]-NNN / AC-[PREFIX]-NNN.N acceptance criteria. Supports nested sub-features with appended prefixes. Use when the user wants to spec a feature for engineering to build. +allowed-tools: + - AskUserQuestion + - Read + - Write + - Glob + - Grep + - Bash(rm:*) +--- + +# FRD: Write a Feature Requirements Document + +## Purpose + +Produce a single `.frd.md` file engineers can build from. FRDs follow a consistent three-section structure: **Overview**, **Terminology**, **Requirements**. + +## Shared Operating Model + +Use `requirements-operating-model` before writing when the task touches Product Overview context, existing FRDs, feature hierarchy, ambiguous behavior, or downstream Blueprint / Work Order impact. Use its clarification pattern instead of creating a separate local questioning workflow. + +## When to Use + +- The user has a feature in mind and needs it specified +- A Product Overview Document (the `prd-*` files) describes the product shape; a specific feature still needs to be pinned down +- A vague ticket needs to be turned into something testable + +## Resolve Project, Prefix, and Parent + +### Project + +Determine `projectid`: + +1. If supplied, use it verbatim. +2. Otherwise, ask once. `Glob` `.trogonai/project/*/` to offer existing projects. + +### Parent FRD (sub-feature check) + +Ask: **is this a top-level feature, or a sub-feature of an existing FRD?** + +Apply the sub-feature rule strictly: a child is only a child if **the parent delivers complete value on its own and the child is meaningless without the parent**. If the user describes it as a child but the parent would not work without it, push back; that means it should be merged, not nested. + +- **Top-level** → file: `.trogonai/project/{projectid}/frd/{slug}.frd.md` +- **Child** → `Glob` existing FRDs to pick the parent: + - If parent is at `frd/{parent-slug}.frd.md`, promote to `frd/{parent-slug}/index.frd.md` first (read, write to new path, remove the old file with `rm` only after the new index exists). + - Write child at `frd/{parent-slug}/{slug}.frd.md`. + - Deeper nesting follows the same pattern recursively. + +If the target file already exists, read it first and ask **replace** or **refine**. + +### Product Context + +Before discovery, read the relevant Product Overview files when they exist: + +- `personas.prd.md` for user-story roles +- `product-description.prd.md` for product surfaces and boundaries +- `business-problem.prd.md` and `current-state.prd.md` for the user pain and status quo +- `success-metrics.prd.md` for outcome priority +- `technical-requirements.prd.md` for constraints that acceptance criteria must respect + +Also read nearby FRDs that share the same parent, prefix family, or product surface. If the new requirement duplicates an existing requirement, refine the owner instead of creating a second source of truth. + +### ID Convention + +Requirements and acceptance criteria use stable IDs so they can be referenced unambiguously from code, commits, tickets, tests, and reviews. + +- **`REQ-`** stands for **Requirement**: a single cohesive, independently testable capability. +- **`AC-`** stands for **Acceptance Criterion**: one observable behavior the system must exhibit to satisfy its parent requirement. + +Format: + +- Requirement id: `REQ-{PREFIX}-NNN` (e.g., `REQ-CHK-003`). +- Acceptance criterion id: `AC-{PREFIX}-NNN.N`, where `NNN` matches its parent requirement (e.g., `AC-CHK-003.2` is the 2nd acceptance criterion of `REQ-CHK-003`). + +### Prefix + +Every FRD has a short uppercase prefix used inside its requirement and acceptance ids. + +- **Top-level FRDs:** ask the user for a 2–4 letter prefix derived from the feature name (e.g., `CHK` for Checkout, `AUTH` for Auth). Confirm uniqueness by `Grep`-ing existing FRDs in the project for `REQ--`. +- **Child FRDs:** the prefix is the parent's prefix + `-` + a 2–3 letter sub-prefix specific to the child (e.g., parent `AUTH` + child Password Reset → `AUTH-PR`). The full requirement id then looks like `REQ-AUTH-PR-001`. + +## Discovery + +### 1. Overview + +Drive the user to produce **1–2 narrative paragraphs** answering: + +- What the feature does +- Why users need it (problem solved, value delivered) +- How it relates to the rest of the product (integrations, dependencies, but not implementation) + +A stakeholder should understand the purpose in under a minute. Reject paragraphs that describe mechanisms or implementation: the Overview is purpose, not design. + +### 2. Terminology + +Ask: *"Which terms specific to this feature could be misunderstood?"* + +- Define only feature-specific terms. Do **not** define industry-standard terms (e.g., "API", "user"). +- Each definition is brief and precise. +- Use the template's term-definition shape: `- **Term:** Definition`. +- If no ambiguous terms exist, the section may be omitted. + +### 3. Requirements + +Each requirement represents **one cohesive, independently testable capability**. + +For each requirement, drive: + +- **Title**: short, capability-shaped (e.g., "Payment Confirmation", not "Show stuff"). +- **User story**: exactly one sentence in the form *"As a [role], I want to [action], so that I can [outcome]."* The role must be a concrete persona. If `personas.prd.md` exists in the project, the role must match (or the deviation must be justified). +- **Acceptance criteria**: one or more `AC-[PREFIX]-NNN.N` items. Each criterion follows: + - **"When [condition], the system shall [behavior]."**: mandatory + - **"When [condition], the system should [behavior]."**: recommended + - **"When [condition], the system may [behavior]."**: optional + +Quality bar for requirements: + +- **User-centered**: describes what users need, not internal mechanics. +- **Testable**: every AC is clear enough to write a test against. +- **Atomic**: each AC covers exactly one behavior. Split compound ACs. +- **Coverage**: at least one happy-path AC and at least one failure / edge-case AC per requirement (invalid input, missing permission, conflict, empty state, network failure). + +Numbering: requirements are sequential, zero-padded to three digits (`001`, `002`, ...). ACs within a requirement are `NNN.N` (`001.1`, `001.2`, ...). + +### 4. Optional Extension Sections + +After requirements are stable, decide whether the FRD needs any extension section beyond the guide's three-section shape. + +- Add `## Child FRDs` only when this FRD has children. +- Capture cross-requirement interactions, defaults, constraints, precedence rules, and edge conditions as acceptance criteria whenever possible. +- Add other extension sections only when the project's Feature Requirements Template provides them. +- If no extension content is needed, omit the extension section entirely. Do not add a placeholder. + +### 5. Split check + +If the discovery surfaces more than roughly **5 requirements**, or requirements covering capabilities a different team would own, recommend `frd-split` rather than producing a sprawling FRD. + +## Output + +Resolve the template source before writing: + +1. If the user or project context provides a Project Settings > Requirements > Feature Requirements Template, read and use that template. +2. Otherwise, use the bundled default at `assets/frd-template.md`. + +Write a single file using the resolved template. Substitute the placeholders (feature name, `{projectid}`, `{PREFIX}`, parent path, date), repeat the `REQ-{PREFIX}-NNN` block once per requirement, and fill in each section from the discovery output. + +After writing, if a parent FRD exists, append an entry to its `## Child FRDs` section (creating the section if missing): + +```markdown +- [{child-slug}](./{child-slug}.frd.md): +``` + +If refining an existing FRD, call out likely downstream Blueprint or Work Order follow-up when user stories, acceptance criteria, requirement IDs, feature boundaries, or technical constraints changed. Do not edit downstream modules from this skill. + +## Good vs Bad Example + +**Good** + +``` +REQ-CHK-003: Payment Confirmation + +User Story: As a customer, I want to receive confirmation after my payment is processed, so that I can know my order was placed successfully. + +Acceptance Criteria: +- AC-CHK-003.1: When payment processing succeeds, the system shall display a confirmation page with the order number and estimated delivery date. +- AC-CHK-003.2: When payment processing fails, the system shall return the user to the payment form with an error message describing the failure reason. +- AC-CHK-003.3: When the user navigates away during processing, the system shall complete the transaction and display the confirmation on their next visit. +``` + +**Bad** (reject this shape) + +``` +REQ-CHK-003: Payment Confirmation + +User Story: As a user, I want payment to work. + +Acceptance Criteria: +- AC-CHK-003.1: The system should show a message. +- AC-CHK-003.2: Errors should be handled appropriately. +``` + +The user story has no outcome and uses a generic role. The ACs are untestable: "show a message" and "handled appropriately" do not describe specific behaviors. + +## Anti-Patterns to Reject + +- "As a user, I want X": generic role; force a concrete persona. +- ACs without a "When" condition. +- ACs using "the system handles X appropriately" are not testable. +- One AC describing multiple behaviors: split. +- Overview that describes implementation ("uses Stripe webhooks") instead of purpose. +- Terminology entries for industry-standard terms. +- Calling something a sub-feature when the parent depends on it; that is a merge, not a nest. +- Extension sections that prescribe UI, screens, or user flows. +- Extension sections that restate per-requirement ACs instead of owning new context. +- Empty extension sections with placeholder text. + +## Related Skills + +- `frd-split`: break an FRD into independently-valuable parent + nested children +- `frd-review`: audit an FRD or a tree of FRDs +- `frd-getting-started`: produce the initial set of FRDs for a new project +- `prd-personas`: define personas that user stories reference + +## Allowed Tools + +- **AskUserQuestion**: drive discovery, prefix selection, parent picking +- **Read**: load parent FRD and personas +- **Write**: create the FRD file and update parent's Child FRDs list +- **Glob**: locate existing FRDs and projects +- **Grep**: check existing requirement prefixes +- **Bash(rm:*)**: remove the original parent file only after promotion to `index.frd.md` succeeds diff --git a/plugins/trogonstack-product-requirements/skills/frd-write/assets/frd-template.md b/plugins/trogonstack-product-requirements/skills/frd-write/assets/frd-template.md new file mode 100644 index 0000000..557fa80 --- /dev/null +++ b/plugins/trogonstack-product-requirements/skills/frd-write/assets/frd-template.md @@ -0,0 +1,37 @@ +# + +- **Project:** {projectid} +- **Prefix:** {PREFIX} +- **Parent FRD:** +- **Status:** Draft +- **Last updated:** + +## Overview + +Provide a clear and concise summary of the feature, explaining what it does and the value it delivers to the user. Describe the core problem this feature solves and how it fits into the overall product. + +## Terminology + +- **Key Term 1:** Brief description that ensures shared understanding across the team. +- **Key Term 2:** Definition that clarifies any ambiguity in how this concept is used. + +## Requirements + +### REQ-{PREFIX}-001: Requirement Name + +**User Story:** As a [role], I want to [perform action], so that I can [achieve outcome]. + +**Acceptance Criteria:** + +- AC-{PREFIX}-001.1: When the user [performs action], the system shall [respond with specific, observable behavior]. +- AC-{PREFIX}-001.2: When [failure / edge condition occurs], the system shall [observable behavior, e.g., return error code, display named message, persist record]. +- AC-{PREFIX}-001.N: [Continue for all acceptance criteria: each atomic, each testable] + +### REQ-{PREFIX}-002: Requirement Name + +**User Story:** As a [role], I want to [perform action], so that I can [achieve outcome]. + +**Acceptance Criteria:** + +- AC-{PREFIX}-002.1: When [condition], the system shall [behavior]. +- AC-{PREFIX}-002.2: [Continue for all acceptance criteria] diff --git a/plugins/trogonstack-product-requirements/skills/prd-business-problem/SKILL.md b/plugins/trogonstack-product-requirements/skills/prd-business-problem/SKILL.md new file mode 100644 index 0000000..262890c --- /dev/null +++ b/plugins/trogonstack-product-requirements/skills/prd-business-problem/SKILL.md @@ -0,0 +1,155 @@ +--- +name: prd-business-problem +description: Draft the Business Problem of a PRD by framing the core problem the product addresses, the gaps in today's tools and processes, and why change is necessary now. Drives discovery through who experiences the pain, what fails today, and the cost of inaction. Writes to `.trogonai/project/{projectid}/prd/business-problem.prd.md`. Use when the user wants to write, refine, or audit the problem framing of a product or feature. +allowed-tools: + - AskUserQuestion + - Read + - Write +--- + +# PRD: Business Problem + +## Purpose + +Produce the **Business Problem** file of a PRD: the core problem the product addresses, what current tools and processes fail to solve, and why change is necessary now: grounded in evidence. + +## Shared Operating Model + +Use `requirements-operating-model` when the problem framing depends on existing product context, artifacts, unclear source of truth, or clarification before editing. + +## When to Use + +- The user is starting a PRD and needs to frame the problem +- An existing PRD has a vague problem statement that needs sharpening +- The user is pitching an idea and needs to validate there is a real problem before designing a solution + +## Project Identifier + +Before writing, determine the `projectid`: + +1. If the user has supplied one, use it verbatim. +2. Otherwise, ask for it once. The `projectid` should be a stable, kebab-case identifier for the product/initiative (e.g., `onboarding-revamp`, `realtime-collab`). +3. Confirm the resolved path before writing: `.trogonai/project/{projectid}/prd/business-problem.prd.md`. + +If the file already exists, read it first and ask whether to **replace** or **refine** before overwriting. + +## Discovery + +Ask until all three areas are answered concretely. Each section of the template must be backed by evidence (data, tickets, quotes, lost deals, churn signals): opinion alone is not evidence. + +1. **The Problem** + - Who experiences it? Specific user segment: role, team, persona. Reject "users", "everyone", "our customers". + - What pain does it cause, in their words? Symptom and observable behavior, not a missing feature. Reject solution-shaped answers like "we need a dashboard". + - Why does it matter? The business or user impact in concrete terms. + +2. **Current Gaps** + - What tools, processes, or systems do people use today to cope? + - Where do those fail: workarounds, manual effort, missing capability, fragmented data, blind spots? + - Why are those gaps significant rather than minor inconveniences? + +3. **Why Change Is Necessary** + - What is the trigger making this urgent now: a market shift, a deadline, an escalation, a strategic bet? + - What happens if nothing changes in the next quarter / year? + - What opportunity is at risk: revenue, retention, competitive position, regulatory standing? + +If the user describes a solution, ask: *"What pain does that solve, for whom, and how do you know they have it?"* Restart from step 1. + +If the user describes a metric improvement ("increase conversion"), ask: *"What is the user-facing symptom that drives that metric today?"* + +## Quality Bar + +The file is complete when: + +- A reader unfamiliar with the project can name the affected user segment and the pain they feel +- Current Gaps name real tools, processes, or systems, not abstractions like "the current experience" +- Why Change Is Necessary points to a concrete trigger and a named consequence of inaction +- At least one concrete piece of evidence (a number, a quote, a ticket count, a lost deal) is woven into the document, not just "we hear this a lot" + +## Output + +Write the complete file to `.trogonai/project/{projectid}/prd/business-problem.prd.md` using the template at `assets/business-problem-template.md`. Read it, substitute `{projectid}` and the date, and fill in each section from the discovery output. + +## Writing Guidance + +### Writing approach +- **Complete paragraphs, not bullet grids.** Each section is prose that tells a story and supplies context. Lists belong inside paragraphs only when they enumerate concrete evidence. +- **Defend every claim.** A problem statement, a gap, or a "why now" is only acceptable when paired with the reasoning or evidence that supports it. If a sentence could be deleted without losing the argument, delete it. +- **Lead with the why before the what.** The reader is a stakeholder deciding whether this is worth doing. Anchor on motivation; mechanics belong in `prd-product-description`. +- **Weave evidence into the prose.** Numbers, quotes, and named incidents belong inside the paragraphs, not in a separate evidence list. + +### Tone and language +- **Active voice and concrete nouns.** Name the actor, the action, and the object. "Reps re-enter notes" beats "notes are re-entered." +- **No fluffy adjectives.** Forbidden words include *comprehensive, sophisticated, seamless, powerful, engaging, robust, world-class, cutting-edge, next-generation*. If the sentence relies on one of these, rewrite it with a measurable fact. +- **Readable by both technical and non-technical stakeholders.** No internal acronyms, no jargon without a definition the first time it appears. + +### Scope +- **Problem, not solution.** Anything that prescribes how to build, what the UI looks like, or which technology to use is out of scope here. Park solution ideas for `prd-product-description`. +- **No invention.** Every claim must come from the user's input or named project context (interviews, tickets, dashboards, contracts). If a fact is not available, ask for it rather than fabricating one. + +## Good vs Bad Example + +**Good** + +``` +## The Problem +Mid-market sales reps at companies of 200–2000 employees who manage 30–80 active +deals at once in Salesforce spend 45–60 minutes per day re-entering deal notes +from Zoom calls. They miss follow-ups because notes live in three places +(Zoom chat, their notebook, Salesforce), and managers cannot see deal status +without DMing the rep. This matters because forecast accuracy and rep retention +both depend on the system of record being current. + +## Current Gaps +Today reps stitch together Zoom's auto-transcripts, a personal notebook, and +manual Salesforce entry. Salesforce's native call logging requires reps to +re-listen to recordings; Zoom AI Companion does not write back to Salesforce; +internal Zapier flows break weekly because Zoom topic strings change. The +result is that the "next steps" field is blank for 38% of deals at week 2 of +the cycle, leaving managers without the signal they need to coach or +intervene. + +## Why Change Is Necessary +Q3 forecast accuracy dropped from 78% to 61% and the CFO escalated to the CRO. +Two enterprise deals slipped last quarter because follow-ups were missed, +representing $1.4M in lost ARR. Six of the last nine AE exit interviews cited +"tooling frustration" as a reason for leaving. If nothing changes, we expect +forecast accuracy to keep declining into Q4 board reviews and to lose another +2–3 AEs we cannot afford to backfill before renewal season. +``` + +**Bad** + +``` +## The Problem +Our users find the current experience frustrating and want something better. + +## Current Gaps +The existing tools do not work very well and customers have been asking for +improvements. + +## Why Change Is Necessary +We need to improve the product to stay competitive and keep up with industry +trends. +``` + +The bad version has no segment, no observable pain, no named tools, no +quantified consequence, and no real evidence: every line could apply to any +product. A reader is no more motivated after reading it than before. + +## Anti-Patterns to Reject + +- "Users want a better experience" is not a problem, has no segment, and offers no evidence. +- "We need feature X": solution stated as problem. +- "Conversion is low": metric, not a user pain. +- "Customers have asked for this": push for how many, who specifically, and what they actually said. +- "Industry trend": push for how it shows up for *this* user segment. +- "The current tools are bad" in Current Gaps: name the actual tools and the specific failure mode. +- Fluffy adjectives: "comprehensive", "seamless", "powerful", "engaging" and similar. Replace with a measurable fact. +- Passive voice that hides the actor: "notes are missed" → who misses them, and how often. +- Any claim that cannot be traced back to user input or named project context: ask, do not invent. + +## Allowed Tools + +- **AskUserQuestion**: drive discovery and resolve `projectid` +- **Read**: load the existing file if it exists, to decide replace vs refine +- **Write**: write the file diff --git a/plugins/trogonstack-product-requirements/skills/prd-business-problem/assets/business-problem-template.md b/plugins/trogonstack-product-requirements/skills/prd-business-problem/assets/business-problem-template.md new file mode 100644 index 0000000..7d8e069 --- /dev/null +++ b/plugins/trogonstack-product-requirements/skills/prd-business-problem/assets/business-problem-template.md @@ -0,0 +1,16 @@ +# Business Problem + +- **Project:** {projectid} +- **Last updated:** + +## The Problem + + +## Current Gaps + + +## Why Change Is Necessary + diff --git a/plugins/trogonstack-product-requirements/skills/prd-current-state/SKILL.md b/plugins/trogonstack-product-requirements/skills/prd-current-state/SKILL.md new file mode 100644 index 0000000..d50618f --- /dev/null +++ b/plugins/trogonstack-product-requirements/skills/prd-current-state/SKILL.md @@ -0,0 +1,131 @@ +--- +name: prd-current-state +description: Draft the Current State of a PRD by documenting the status quo the product improves upon. Drives discovery through what users do today, the workarounds in use, the costs of the status quo, and the alternatives that already exist. Writes to `.trogonai/project/{projectid}/prd/current-state.prd.md`. Use when the user wants to document the baseline before proposing a change. +allowed-tools: + - AskUserQuestion + - Read + - Write +--- + +# PRD: Current State + +## Purpose + +Describe the status quo the product is intended to improve upon, so the value of the change is measurable and the "do nothing" baseline is explicit. + +## Shared Operating Model + +Use `requirements-operating-model` when the current-state baseline depends on existing product context, artifacts, unclear source of truth, or clarification before editing. + +## When to Use + +- A new PRD needs its baseline documented +- An existing PRD jumps to the solution without describing what exists today +- The user wants to justify investment by quantifying the cost of the current state + +## Project Identifier + +Before writing, determine the `projectid`: + +1. If the user has supplied one, use it verbatim. +2. Otherwise, ask for it once. The `projectid` should be a stable, kebab-case identifier for the product/initiative. +3. Confirm the resolved path before writing: `.trogonai/project/{projectid}/prd/current-state.prd.md`. + +If the file already exists, read it first and ask whether to **replace** or **refine** before overwriting. + +## Discovery + +Ask until all are answered: + +1. **What do affected users do today** to get the job done? Walk through the actual steps, tools, and handoffs. +2. **What workarounds are in use?** Spreadsheets, manual processes, copy-paste, side scripts, hiring more humans. Workarounds are the strongest evidence of unmet need. +3. **What alternatives already exist**: internal tools, competitor products, third-party services? Why are they not used, or why are they insufficient? +4. **What does the current state cost?** Time per task, error rate, support load, lost revenue, abandonment, hours of toil. Quantify where possible. +5. **What is intentionally left alone?** Parts of the current state that are acceptable and not in scope to change. + +Push back on "there is no current process": there is always a current state, even if it is "users do not do this at all and the business loses the opportunity". + +## Quality Bar + +The file is complete when: + +- The current workflow can be reconstructed by a reader who has never used the product +- At least one quantified cost is present (time, money, error rate, volume) +- Workarounds are named, not implied +- The relationship to existing alternatives (internal or external) is explicit + +## Output + +Write the complete file to `.trogonai/project/{projectid}/prd/current-state.prd.md` using the template at `assets/current-state-template.md`. Read it, substitute `{projectid}` and the date, and fill in each section from the discovery output. + +## Writing Guidance + +### Writing approach +- **Reconstruct the workflow concretely.** Walk a reader through the actual steps users take today, in the order they take them, with the tools they touch. Skipping a step hides the friction it causes. +- **Name workarounds and tools by name.** "A spreadsheet" is invisible; "a shared Google Sheet titled `Pipeline Reconciliation v7`" is evidence. Workarounds are the strongest signal of unmet need: give them the page space they deserve. +- **Quantify the cost.** Every cost in the table needs a number with a unit and a source. "A lot" is not a cost. +- **Treat alternatives honestly.** Internal tools, competitors, third-party services: say what they do and *why they fall short for this user*, not why they are bad in general. + +### Tone and language +- **Plain language.** Anyone in the company should be able to read this and understand what users do today, without internal jargon. +- **Specific, not impressionistic.** "Slow" is impressionistic; "45 minutes per deal" is specific. The reader should feel the friction. +- **Cost, not complaint.** Translate complaints into observable cost: time, errors, lost revenue, headcount, abandonment. + +### Scope +- **Today, not tomorrow.** Resist sliding into the desired state. Future workflow belongs in `prd-product-description`. +- **Baseline, not solution.** Even when a workaround obviously points to a feature, this file documents the workaround: feature proposals live in `prd-product-description` and FRDs. +- **No invention.** Every step, workaround, and cost must come from observed behavior, interviews, dashboards, or tickets. If the source is unknown, ask rather than guess. + +## Good vs Bad Example + +**Good** + +``` +## How the job gets done today +1. Rep finishes a Zoom call. Notes are in Zoom chat, a physical notebook, or both. +2. Rep opens Salesforce, finds the right opportunity, copy-pastes notes into the Activity log. +3. Rep manually edits the "Next Steps" field. ~40% of the time this field is skipped because the rep is on their next call. +4. Manager pulls the deal report Monday morning; for deals with blank fields, manager DMs the rep individually. + +## Workarounds in use +- Personal Notion / Apple Notes pages: 7 of 12 reps maintain a parallel deal tracker because Salesforce notes are not searchable from mobile. +- Weekly "pipeline review" meeting (60 min, 14 attendees) exists primarily to reconcile what Salesforce says vs what reps actually know. + +## Cost of the status quo +| Cost | Measure | Source | +|------|---------|--------| +| Rep time on Salesforce data entry | 45–60 min/day per rep × 22 reps | Time-tracking survey, Mar 2026 | +| Forecast accuracy | 61% (down from 78% YoY) | Salesforce forecast vs actual close | +| Manager toil chasing notes | ~6 hours/week per sales manager | Manager interviews, 4/5 | +``` + +**Bad** + +``` +## How the job gets done today +1. Users use Salesforce. +2. They enter their notes. + +## Workarounds in use +- People do things outside the system sometimes. + +## Cost of the status quo +| Cost | Measure | Source | +|------|---------|--------| +| Time | A lot | Anecdote | +``` + +The bad version is unfalsifiable: no reader can act on it. The good version names actors, counts steps, and quantifies cost with a source. + +## Anti-Patterns to Reject + +- "Nothing exists today": there is always a status quo, including doing nothing. +- "It's slow": push for a number. +- "Users complain": push for what they do instead, and the cost of doing it. +- Describing the future state in this file; that belongs in `prd-product-description`. + +## Allowed Tools + +- **AskUserQuestion**: drive discovery and resolve `projectid` +- **Read**: load the existing file if it exists, to decide replace vs refine +- **Write**: write the file diff --git a/plugins/trogonstack-product-requirements/skills/prd-current-state/assets/current-state-template.md b/plugins/trogonstack-product-requirements/skills/prd-current-state/assets/current-state-template.md new file mode 100644 index 0000000..6b6bd37 --- /dev/null +++ b/plugins/trogonstack-product-requirements/skills/prd-current-state/assets/current-state-template.md @@ -0,0 +1,23 @@ +# Current State + +- **Project:** {projectid} +- **Last updated:** + +## How the job gets done today +1. +2. +3. + +## Workarounds in use +- : + +## Existing alternatives +- : + +## Cost of the status quo +| Cost | Measure | Source | +|------|---------|--------| +|