From 4ae320ce1c506f283a1449faddaf2bfc8c6f57b4 Mon Sep 17 00:00:00 2001 From: Jaydeep Joshi <68891090+jaydeep-helpshift@users.noreply.github.com> Date: Thu, 30 Jul 2026 11:21:47 +0000 Subject: [PATCH] Add build-prd skill for Helpshift Product Overview docs Introduces a project Cursor skill that drafts PRDs using the official PMT Product Overview template, mandatory cross-cutting stories, and discovery best practices. Co-authored-by: KrishnaMB-PM --- .cursor/skills/build-prd/SKILL.md | 119 +++++++++++++ .cursor/skills/build-prd/best-practices.md | 105 ++++++++++++ .cursor/skills/build-prd/template.md | 190 +++++++++++++++++++++ 3 files changed, 414 insertions(+) create mode 100644 .cursor/skills/build-prd/SKILL.md create mode 100644 .cursor/skills/build-prd/best-practices.md create mode 100644 .cursor/skills/build-prd/template.md diff --git a/.cursor/skills/build-prd/SKILL.md b/.cursor/skills/build-prd/SKILL.md new file mode 100644 index 00000000..75b1a0d9 --- /dev/null +++ b/.cursor/skills/build-prd/SKILL.md @@ -0,0 +1,119 @@ +--- +name: build-prd +description: Build Helpshift Product Overview (PRD/PO) documents using the official PMT template and product best practices. Use when creating a PRD, Product Overview, PO doc, feature requirements, product requirements document, or when the user asks to draft, write, or structure requirements for a feature. +--- + +# Build PRD (Product Overview) + +Create Helpshift **Product Overview (PO)** documents — the team's PRD format — following the official template and discovery best practices. + +**Canonical template:** [Template - Product Overview for a feature](https://helpshift.atlassian.net/wiki/spaces/PMT/pages/4427612355/Template+-+Product+Overview+for+a+feature) + +**Related:** [Product Research/Discovery template](https://helpshift.atlassian.net/wiki/spaces/PMT/pages/4437803114), [Product Development Playbook](https://helpshift.atlassian.net/wiki/spaces/HE/pages/4711744054) + +## When to use + +- User asks to create/draft a PRD, PO, Product Overview, or feature requirements +- Discovery needs a structured requirements doc for Quad/Squad +- Turning research, interviews, or a Jira initiative into a PO + +## Workflow + +Copy and track: + +``` +PRD Progress: +- [ ] 1. Gather inputs +- [ ] 2. Draft PO sections +- [ ] 3. Add feature + mandatory stories +- [ ] 4. Define metrics, launch, decisions +- [ ] 5. Quality checklist +- [ ] 6. Publish (if requested) +``` + +### Step 1: Gather inputs + +Ask only for what's missing. Prefer parallel search of Confluence/Jira when the feature name or initiative key is known. + +Collect: +- Feature/initiative name and Jira initiative link (if any) +- Problem / as-is workflow +- Target users and current behaviors +- Goals, business case, competitive context +- Constraints, assumptions, out-of-scope +- Design / research links (customer interviews, competitor analysis, Figma) +- Approvers (Product Lead, EM, Designer) and alignment/validation stakeholders +- Parent Confluence page (if publishing) + +If context is thin, draft with clear `TBD` markers rather than inventing facts. + +### Step 2: Draft the PO + +Use the section order in [template.md](template.md). Title format: + +- `PO: ` +- Or phased: `PO: In#N: ` + +**Writing rules:** +- **Summary** — executive overview only; include project type (new feature, enhancement, platform, etc.). No implementation detail. +- **Background** — problem, as-is flow, why now; link customer interview insights. +- **Business case and Goals** — outcomes for customers and for Helpshift; link competitor analysis when relevant. +- **Target Audience** — personas + current workflows/behaviors. +- **High Level Solution** — outcome for the persona; add flow/illustration when useful; list assumptions. Use: `` ` can by doing ` `` +- **Terminology** — only new terms; keep the list short. +- Prefer evidence links over long prose. Call out **Out of Scope** explicitly. + +### Step 3: Requirements (user stories) + +1. Add a **Summary** table: User Story # → Priority/Phase. +2. For each feature story, fill the detail table (story, parent/dependency, description, launch phase, design link, acceptance criteria/UAT). +3. **Always include the mandatory cross-cutting stories** from [template.md](template.md) (identity, app permissions, agent access, dashboard/Metabase analytics, DPIA/legal, security, Custom Analytics & AI Analytics). Adapt wording to the feature; do not drop them without an explicit rationale in Out of Scope / Key Decisions. +4. Acceptance criteria must be testable (Given/When/Then or concrete UAT bullets). +5. Phase stories (Phase 1 / 2 / Later) when scope is large. + +### Step 4: Metrics, launch, decisions + +- **Success Criteria:** feature success ≈ ≥25% overall customer adoption; reports ≈ ≥50% (exceptions case-by-case). +- **Adoption Criteria:** define when a brand counts as regularly using the feature. +- **Launch Strategy:** GTM, roll-out, adoption, pricing. +- **Key Decisions:** date, decision, POC, approval status. +- **Additional Information:** changelog table + supporting links. + +### Step 5: Quality checklist + +Before delivering, verify [best-practices.md](best-practices.md). Minimum bar: + +- [ ] Reader can understand problem + outcome from Summary alone +- [ ] Goals are measurable; success/adoption criteria defined +- [ ] Stories use `As a , I want so that ` +- [ ] Every in-scope story has acceptance criteria +- [ ] Mandatory platform stories present (or explicitly deferred with reason) +- [ ] Out of scope listed +- [ ] Assumptions and dependencies called out +- [ ] No invented customer quotes, metrics, or stakeholder names — use TBD + +### Step 6: Publish (only if asked) + +Publish to Confluence space **PMT** (`spaceId` `4388389216` or key `PMT`) via Atlassian MCP `createConfluencePage`. + +- Prefer `contentFormat: "markdown"` unless HTML is required for Confluence-specific nodes +- Set `parentId` when the user names a parent; otherwise ask or leave under the agreed feature folder +- After create, return the page URL +- Link the PO from the Jira initiative (`PO Link`) when an initiative exists + +Do **not** create Confluence pages unless the user asks to publish. + +## Output + +Default: full PO markdown matching [template.md](template.md), ready to paste into Confluence. + +Also provide a short **open questions** list for anything still TBD. + +## Anti-patterns + +- Jumping to UI/tech detail before problem, audience, and goals +- Stories without acceptance criteria +- Skipping mandatory identity/permissions/analytics/security/DPIA stories silently +- Vague success metrics ("improve engagement") +- Mixing in-scope and out-of-scope without labeling +- Filling Approvers/Alignment with guessed names diff --git a/.cursor/skills/build-prd/best-practices.md b/.cursor/skills/build-prd/best-practices.md new file mode 100644 index 00000000..24693796 --- /dev/null +++ b/.cursor/skills/build-prd/best-practices.md @@ -0,0 +1,105 @@ +# PRD / Product Overview best practices + +Apply these when drafting or reviewing a Helpshift PO. Canonical section order lives in [template.md](template.md). + +## Document purpose + +The Product Overview is the shared artifact for Quad discovery and Squad delivery. It should let Product, Eng, Design, and QA understand the problem, outcome, scope, and acceptance bar without a meeting. + +Progressive elaboration is expected: +- **Inception:** enough for sizing and resource allocation (problem, goals, high-level solution) +- **Discovery:** elaborate personas, flows, stories, UAT, metrics; close open questions +- **Ready for development:** stories with UAT for "Now" epics; designs linked; out of scope clear + +## Section quality bar + +| Section | Do | Don't | +| --- | --- | --- | +| Summary | One short executive read; state project type | Paste full requirements | +| Background | Problem, as-is, why now, evidence links | Solution disguised as problem | +| Goals | Customer + Helpshift outcomes; measurable where possible | Vague "improve UX" | +| Audience | Personas + current behavior | "All users" with no context | +| High Level Solution | Outcome formula + assumptions + optional flow | API/schema dumps | +| Requirements | Prioritized stories + testable UAT + phases | Orphan wish-list bullets | +| Success Metrics | Adoption thresholds + how measured | Vanity metrics only | +| Launch | GTM, roll-out, adoption, pricing | Empty placeholders left forever without TBD | +| Key Decisions | Dated, owned, statused | Undocumented verbal decisions | + +## User story standards + +Format: + +`As a , I want so that ` + +Each story detail table should answer: +1. Who benefits? +2. What changes in the product? +3. Why it matters? +4. What "done" means (Acceptance Criteria/UAT)? +5. Which phase / design / dependency applies? + +Good acceptance criteria: +- Observable outcomes (UI state, data, permissions, notifications) +- Edge cases that matter (multi-device, reopened issues, missing identity, offline) +- Explicit non-goals for that story when helpful + +Weak acceptance criteria: +- "Works as expected" +- "Fast and intuitive" +- Implementation notes with no user-visible check + +## Scope control + +- Keep a visible **Out of Scope** list (and update the changelog when scope moves) +- Slice large initiatives into phases / epics (Now / Next / Later) +- Prefer fewer sharp stories over many overlapping ones +- Capture RAID items (risks, assumptions, issues, dependencies) in Key Decisions or Additional Information when they affect delivery + +## Mandatory cross-cutting stories + +The official template requires sample-but-mandatory stories for: +1. User identity behavior +2. App-level permissions +3. Agent-level access +4. Dashboard analytics + Metabase +5. DPIA / legal review +6. Security guidelines +7. Custom Analytics & AI Analytics + +Adapt each to the feature. If one does not apply, record that in **Key Decisions** or **Out of Scope** with owner and rationale — do not silently omit. + +## Metrics defaults (Helpshift) + +- Feature success: aim for ≥25% overall customer adoption unless exception agreed +- Report success: aim for ≥50% adoption unless exception agreed +- Define brand-level **Adoption Criteria** (what usage counts as adopted) + +## Evidence and links + +Link rather than restate: +- Customer interview insights +- Competitor analysis +- Figma / Whimsical flows +- Jira initiative and related epics +- Prior PO / discovery docs + +## Publishing conventions + +- Space: **PMT** +- Title: `PO: ` or `PO: In#N: ` +- Keep Approvers / Alignment / Validation tables real; use empty rows or TBD — never invent names +- After publish, attach PO URL on the Jira initiative when one exists + +## Example reference + +Filled PO pattern (structure and depth): [PO: In#2: End User Experience for Proactive Outbound Support (SDK)](https://helpshift.atlassian.net/wiki/spaces/PMT/pages/4838228032/PO+In+2+End+User+Experience+for+Proactive+Outbound+Support+SDK) + +Take from strong examples: +- Clear problem framing in Summary/Background +- Phased stories with concrete behavior in Description +- Explicit Out of Scope and dated scope changes +- Design and flow links next to stories + +Avoid copying: +- Placeholder metrics left as TBA without owners +- Unresolved questions buried only in long description text — surface them as Open Questions diff --git a/.cursor/skills/build-prd/template.md b/.cursor/skills/build-prd/template.md new file mode 100644 index 00000000..7e042d2d --- /dev/null +++ b/.cursor/skills/build-prd/template.md @@ -0,0 +1,190 @@ +# Product Overview template + +Source: [Template - Product Overview for a feature](https://helpshift.atlassian.net/wiki/spaces/PMT/pages/4427612355/Template+-+Product+Overview+for+a+feature) + +Copy this structure when drafting. Replace placeholders; remove guidance italics in the final doc. + +```markdown +# PO: + +[Jira initiative link if available] + +## Approvers + +_Product Leads, EM, Designer_ + +| Approver | Department | Status | +| --- | --- | --- | +| | | | + +## Alignment + +_Stakeholders who need to be informed_ + +| POC | Department | Status | +| --- | --- | --- | +| | | | + +## Validation + +_Stakeholders from whom the project needs validation_ + +| POC | Department | Validation | +| --- | --- | --- | +| | | | + +## Terminology + +_New terms only; concise definitions. Prefer fewer new terms._ + +| Term | Meaning | +| --- | --- | +| | | + +## Summary + +Executive overview: what this project accomplishes and project type (new feature / enhancement / platform / etc.). No deep detail. + +## Background + +- Problem being solved +- As-is process flow +- Why work on this now +- Link to customer interview insights + +## Business case and Goals + +- High-level objectives of the product/feature +- Business case (customer value + Helpshift value) +- Link to competitor analysis + +## Target Audience + +Who the target users are; current workflows and behaviors. + +## High Level Solution + +Outcome for the target persona. Flow diagram or illustration when useful. List assumptions. + +` can by doing ` + +### Out of Scope + +- … + +## Requirements + +### Summary + +| User Story # | Priority/Phase | +| --- | --- | +| US1 | Phase 1 | +| … | | + +### Details + +| **User Story#1** | `As a , I want so that ` | +| --- | --- | +| **Parent Story(if any)/Dependency** | | +| **Description of user story(optional)** | | +| **Launch Phase** | | +| **Design Link** | | +| **Acceptance Criteria/UAT** | | + + + +### Mandatory stories (adapt to feature; required unless explicitly deferred) + +| **User Story#N-1** | `As a HS Product Manager, I want this feature to work <> with user identity so that workflows are per expectations` **[Sample Story but mandatory]** | +| --- | --- | +| **Parent Story(if any)/Dependency** | | +| **Description of user story(optional)** | | +| **Launch Phase** | | +| **Design Link** | | +| **Acceptance Criteria/UAT** | | + +| **User Story#N** | `As a HS Product Manager, I want this feature to have <> for App level permission so that access control is per expectations` **[Sample Story but mandatory]** | +| --- | --- | +| **Parent Story(if any)/Dependency** | | +| **Description of user story(optional)** | | +| **Launch Phase** | | +| **Design Link** | | +| **Acceptance Criteria/UAT** | | + +| **User Story#N+1** | `As a HS Product Manager, I want this feature to have agent level access enabled so that customers can choose which agents should use the feature` **[Sample Story but mandatory]** | +| --- | --- | +| **Parent Story(if any)/Dependency** | | +| **Description of user story(optional)** | | +| **Launch Phase** | | +| **Design Link** | | +| **Acceptance Criteria/UAT** | | + +| **User Story#N+2** | `As a HS Product Manager, I want this feature to have basic dashboard analytics and Metabase report(s) enabled so that customers can measure impact right from the start` **[Sample Story but mandatory]** | +| --- | --- | +| **Parent Story(if any)/Dependency** | | +| **Description of user story(optional)** | | +| **Launch Phase** | | +| **Design Link** | | +| **Acceptance Criteria/UAT** | | + +| **User Story#N+3** | `As a HS Product manager, I want this feature to have all aspects covered under DPIA assessment/legal review so that Helpshift is not legally liable` **[Sample Story but mandatory]** | +| --- | --- | +| **Parent Story(if any)/Dependency** | | +| **Description of user story(optional)** | | +| **Launch Phase** | | +| **Design Link** | | +| **Acceptance Criteria/UAT** | | + +| **User Story#N+4** | `As a HS Product Manager, I want this feature to follow security guidelines so that Helpshift system is not prone to unwanted security attacks` **[Sample Story but mandatory]** | +| --- | --- | +| **Parent Story(if any)/Dependency** | | +| **Description of user story(optional)** | | +| **Launch Phase** | | +| **Design Link** | | +| **Acceptance Criteria/UAT** | | + +| **User Story#N+5** | `As a HS Product Manager, I want this feature's analytics in Custom Analytics & AI Analytics so that all the data in Helpshift is accessible for further processing.` **[Sample Story but mandatory]** | +| --- | --- | +| **Parent Story(if any)/Dependency** | | +| **Description of user story(optional)** | | +| **Launch Phase** | | +| **Design Link** | | +| **Acceptance Criteria/UAT** | | + +## Success Metrics + +**Success Criteria:** Specific % overall customer adoption that marks the feature successful. Rule of thumb: features ≥25%; reports ≥50%. Exceptions case-by-case. + +**Adoption Criteria:** Point at which a brand regularly uses the feature and counts as adopted. + +## Launch Strategy + +1. GTM plan +2. Roll-out plan +3. Adoption plan +4. Pricing plan + +## Key Decisions + +| Date | Decision Taken | POC Name | Approval Status | +| --- | --- | --- | --- | +| | | | | + +## Additional Information + +| Date | What changed in brief? | Link to section | +| --- | --- | --- | +| | | | +``` + +## Mandatory story themes (quick map) + +| Theme | Intent | +| --- | --- | +| User identity | Correct behavior with Helpshift identity / user identification | +| App-level permission | Access control at app/workzone permission model | +| Agent-level access | Brands can choose which agents can use the feature | +| Dashboard + Metabase | Baseline analytics/reporting from day one | +| DPIA / legal | Privacy/legal review coverage | +| Security | Follow security guidelines; no new attack surface left unaddressed | +| Custom Analytics & AI Analytics | Data available for further processing in analytics products |