cc-agentic-framework 1.14.1

package/framework/modules/backlog/skills/backlog/building-tickets/EXAMPLES.md

@@ -0,0 +1,561 @@
+# Ticket Examples (v10.1.1)
+
+## Example 1: Frontend Story (Recommended)
+
+### File: 1283-configurable-cards.md
+
+```yaml
+---
+documentType: story
+title: "APM-R: FE: Dashboard: Configurable Cards"
+description: "Allow users to select which cards appear on their dashboard and persist preferences"
+milestone: Feb2026
+priority: P1
+storyPoints: 5
+labels: [apm-r, frontend, feature, ux]
+createdDate: 2025-12-08
+exportedDate: 2025-12-09
+
+jira-ticketId: DAPM-1283
+jira-url: "https://{your-org}.atlassian.net/browse/PROJ-1283"
+jira-parent: DAPM-1171
+jira-related: [DAPM-1200, DAPM-1210]
+jira-blocking: []
+jira-blockedBy: []
+jira-fixVersion: null
+jira-internalNotes: "Coordinate with UX team on card catalog design"
+
+framework-documentation: "@apm-r-app/src/components/Dashboard/README.md"
+framework-milestone: "backlog/milestones/Feb2026.md"
+framework-technicalGuides: ["@apm-r-app/docs/state-management.md"]
+framework-relatedLocal: ["backlog/epics/1171-configurable-dashboard.md"]
+---
+
+# APM-R: FE: Dashboard: Configurable Cards
+
+---
+
+## Description
+
+**Context:**
+
+Users want to customize their dashboard to see only the metrics that matter to them. Currently, all cards are fixed. This story enables flexible dashboard customization with preferences persisted to their browser.
+
+The UX team has designed a simple card selector (side panel with checkboxes). This story implements the frontend experience and localStorage persistence. Backend changes will be in follow-up story DAPM-1210.
+
+**Requirements:**
+
+* Add card selector sidebar with 1-9 card toggles
+* Persist selected cards to localStorage (per browser/device)
+* Update dashboard grid to show/hide cards based on selection
+* Reset button returns to default card layout
+* All selections idempotent (can be toggled multiple times)
+
+**Technical Notes:**
+
+* Follow MUI Drawer pattern for sidebar (already used elsewhere)
+* Use Zustand for state management (existing pattern)
+* localStorage key: `dashboard:cardPreferences:{orgId}`
+* Card order follows default sequence (don't persist order yet - Phase 2)
+
+---
+
+## Acceptance Criteria
+
+* **Verify** users can see all 9 available cards in selector sidebar
+* **Verify** clicking checkbox toggles card visibility on/off
+* **Verify** dashboard reflects changes immediately (no page reload)
+* **Verify** selections persisted to localStorage after toggle
+* **Verify** selections load on page refresh (same cards shown)
+* **Verify** reset button returns to default 9-card layout
+* **Verify** works on desktop (1920px), tablet (iPad), mobile (iPhone 12)
+* **Verify** empty state (0 cards selected) shows helpful message
+* **Verify** no console errors or React warnings
+* **Verify** performance acceptable (toggle <50ms response)
+* **Verify** documentation updated: src/components/Dashboard/README.md
+```
+
+### Key Annotations
+
+✅ **YAML Structure:** All v10.1.1 fields present:
+- Generic fields: documentType, version, title, description, milestone, etc.
+- Jira fields: jira-ticketId, jira-url, jira-parent, jira-related, etc.
+- Framework fields: framework-documentation, framework-milestone, etc.
+
+✅ **Body Structure:**
+- H1 title matches YAML title
+- `---` dividers present
+- Exactly 2 H2 sections: Description, Acceptance Criteria
+- Context as plain paragraphs (not bullets)
+- Requirements as bullets
+- Technical Notes as bullets (no code snippets)
+- 11 Acceptance Criteria (within 8-12 range)
+
+✅ **Content Quality:**
+- Context explains WHY (user need, business value)
+- Requirements are specific and clear
+- Technical Notes reference patterns, not implementations
+- Acceptance Criteria are testable and observable
+
+---
+
+## Example 2: Backend Task (With Dependencies)
+
+### File: 1406-convert-data-layer-promises.md
+
+```yaml
+---
+documentType: task
+title: "APM-R: BE: Data Layer: Convert Methods to Promise-Based"
+description: "Convert all synchronous data layer methods to async/Promise-based for Sentry transaction support"
+milestone: Feb2026
+priority: P0
+storyPoints: 5
+labels: [apm-r, backend, infrastructure]
+createdDate: 2025-12-04
+exportedDate: 2025-12-05
+
+jira-ticketId: DAPM-1406
+jira-url: "https://{your-org}.atlassian.net/browse/PROJ-1406"
+jira-parent: DAPM-1168
+jira-related: [DAPM-1405, DAPM-1400]
+jira-blocking: [DAPM-1407, DAPM-1408]
+jira-blockedBy: []
+jira-fixVersion: null
+jira-internalNotes: null
+
+framework-documentation: "@apm-r-be/src/data-layer/README.md"
+framework-milestone: "backlog/milestones/Feb2026.md"
+framework-technicalGuides:
+  - "@apm-r-be/docs/transaction-tracing.md"
+  - "@apm-r-be/docs/data-layer-v2.md"
+framework-relatedLocal:
+  - "backlog/epics/1168-centralized-data-layer.md"
+  - "backlog/tickets/tasks/1405-add-sentry-transactions.md"
+---
+
+# APM-R: BE: Data Layer: Convert Methods to Promise-Based
+
+---
+
+## Description
+
+**Context:**
+
+DAPM-1032 implemented V2 data layer architecture (Fetch Controllers, Data Mapping, Zustand Store). However, all data layer methods currently use synchronous patterns. Sentry transactions require **Promise-based methods** so we can properly `await` completion before the transaction finishes.
+
+Without Promises, Sentry transactions may close before data fetching completes, breaking trace correlation and timing accuracy.
+
+**Requirements:**
+
+* Audit all Fetch Controller methods in data layer (identify corner cases)
+* Convert all synchronous methods to `async` functions returning `Promise<T>`
+* Ensure all controller methods return Promises to clients
+* Update page-level code to `await` data layer calls
+* Verify correct promise chaining for parallel fetches
+* Ensure everything ready for Sentry transaction integration (DAPM-1407)
+
+**Technical Notes:**
+
+* V2 architecture (DAPM-1032) is already in place
+* Promise-based allows: `await dataLayerCall()` pattern for Sentry wrapping
+* TanStack Query hooks already return Promises (native behavior)
+* Keep existing component code unchanged - only data layer internals change
+* Follow Promise pattern established in DAPM-1405
+
+---
+
+## Acceptance Criteria
+
+* **Verify** all Fetch Controller methods are Promise-based
+* **Verify** methods use `async` keyword and return `Promise<T>`
+* **Verify** data layer calls return Promises to clients
+* **Verify** page-level hooks properly `await` completion
+* **Verify** unit tests confirm all methods return Promises
+* **Verify** integration tests verify correct promise chains
+* **Verify** no timing regressions vs. previous synchronous approach
+* **Verify** PCR Analyzer pages load correctly, no loading state issues
+* **Verify** error states handled properly (Promise rejection)
+* **Verify** performance acceptable (<500ms data fetch)
+* **Verify** no console errors or unhandled promise rejections
+* **Verify** documentation updated: src/data-layer/README.md
+```
+
+### Key Annotations
+
+✅ **Task vs. Story:** No "AS/WANT/SO THAT" - it's a technical task
+
+✅ **Dependencies:**
+- `jira-blockedBy: []` - This task has no blockers
+- `jira-blocking: [DAPM-1407, DAPM-1408]` - This blocks follow-up Sentry tasks
+- Context references related tasks (DAPM-1032, DAPM-1405)
+
+✅ **Technical Specificity:**
+- Context explains the "why" (Sentry needs Promise-based methods)
+- Requirements are concrete (convert methods to async)
+- Technical Notes reference patterns and existing code
+
+✅ **Acceptance Criteria:**
+- Mix of functional (methods return Promises) and non-functional (performance, documentation)
+- Testable and observable conditions
+
+---
+
+## Example 3: Epic (High-Level)
+
+### File: 1171-configurable-dashboard.md
+
+```yaml
+---
+documentType: epic
+title: "APM-R: Risk Analytics: Configurable Dashboard"
+description: "Enable users to customize dashboards to see metrics that matter to their role and workflow"
+milestone: Feb2026
+priority: P1
+labels: [apm-r, frontend, epic, feature]
+createdDate: 2025-12-01
+exportedDate: 2025-12-02
+
+jira-ticketId: DAPM-1171
+jira-url: "https://{your-org}.atlassian.net/browse/PROJ-1171"
+jira-parent: null
+jira-related: [DAPM-1100, DAPM-1110]
+jira-blocking: []
+jira-blockedBy: []
+jira-fixVersion: null
+jira-internalNotes: null
+
+framework-documentation: null
+framework-milestone: "backlog/milestones/Feb2026.md"
+framework-technicalGuides: ["@apm-r-app/docs/dashboard-architecture.md"]
+framework-relatedLocal:
+  - "backlog/milestones/Feb2026.md"
+  - "ai/context/business-advanced.md"
+---
+
+# APM-R: Risk Analytics: Configurable Dashboard
+
+---
+
+## Description
+
+**Business Value:**
+
+Users want personalized dashboards - different roles need different metrics. Risk Analysts focus on engine performance, Traders focus on position impact, Managers focus on exposure summary. Currently, all users see identical fixed layouts, forcing them to search for relevant metrics.
+
+By enabling customization, we directly improve user productivity and decision speed. Early customer feedback rates this as highest-priority feature request.
+
+**Technical Scope:**
+
+Implement flexible dashboard builder with card selection and layout persistence. Vertical slicing enables FE customization first, BE data optimization second, allowing quick customer launch.
+
+*Child Stories (Implementation Steps):*
+* [DAPM-1283] Frontend: Card Selector UI & localStorage Persistence
+* [DAPM-1284] Backend: Optimize GraphQL Query Selection for Custom Cards
+* [DAPM-1285] Analytics: Track Card Selection Usage Patterns
+* [DAPM-1286] Polish: Mobile Responsiveness & A/B Testing
+
+---
+
+## Acceptance Criteria
+
+* **Verify** all 4 child stories completed and deployed
+* **Verify** end-to-end: Users can select cards → See custom dashboard → Preferences persist
+* **Verify** Query optimization reduces average response by 20% (vs. requesting all fields)
+* **Verify** Dashboard loads in <1s on 3G network (vs. current 2-3s)
+* **Verify** Mobile experience identical to desktop
+* **Verify** A/B testing ready (can measure impact on user engagement)
+* **Verify** Analytics data validates usage patterns (which cards selected, least popular)
+* **Verify** Integration testing passes across all components
+* **Verify** Documentation updated with customization architecture
+* **Verify** Customer training materials prepared
+```
+
+### Key Annotations
+
+✅ **Epic Structure:**
+- Business value clearly stated (user productivity, customer feedback)
+- Technical scope is high-level (mentions "vertical slicing" pattern)
+- Child stories listed as implementation steps with ticket numbers
+
+✅ **NO story points:** Epics don't have story points (child stories do)
+
+✅ **Parent/Related:**
+- No jira-parent (this is a top-level epic)
+- jira-related references other initiatives
+
+✅ **Concise (39 lines):** Within 30-50 line target for epics
+
+---
+
+## Example 4: Bug Report
+
+### File: 1315-shimmer-loading-state.md
+
+```yaml
+---
+documentType: bug
+title: "APM-R: FE: Assets: Fix Shimmer Loading State When Changing Analysis Hours"
+description: "Loading shimmer appears for 5+ seconds when users change analysis hours, indicating performance regression"
+milestone: Feb2026
+priority: P0
+storyPoints: 3
+labels: [apm-r, frontend, bug, performance]
+createdDate: 2025-12-07
+exportedDate: null
+
+jira-ticketId: null
+jira-url: null
+jira-parent: null
+jira-related: [DAPM-1400]
+jira-blocking: []
+jira-blockedBy: []
+jira-fixVersion: null
+jira-internalNotes: "Regression from DAPM-1400 commit a3f2b1c"
+
+framework-documentation: null
+framework-milestone: "backlog/milestones/Feb2026.md"
+framework-technicalGuides: []
+framework-relatedLocal: []
+---
+
+# APM-R: FE: Assets: Fix Shimmer Loading State When Changing Analysis Hours
+
+---
+
+## Description
+
+**Context:**
+
+Users report 5+ second loading delays when changing analysis hours on the Assets page. A shimmer skeleton loader appears and persists for too long, creating poor user experience and suggesting performance problems.
+
+Root cause: Recent refactor in DAPM-1400 likely introduced inefficient re-computation or redundant data fetches. This is a regression - previous version had <1s load time.
+
+**Symptoms:**
+
+* User changes analysis hours (e.g., from 24h to 7d)
+* Shimmer skeleton appears
+* Shimmer persists for 5-10 seconds
+* Data finally appears
+
+**Technical Notes:**
+
+* Regression timeline: Started after DAPM-1400 merged (commit a3f2b1c)
+* Check React profiler for excessive re-renders
+* Verify TanStack Query cache invalidation not triggering unnecessary fetches
+* Profile with Chrome DevTools to identify bottleneck (computation vs. network)
+
+---
+
+## Acceptance Criteria
+
+* **Verify** loading time <1 second when changing analysis hours (baseline vs. <1s target)
+* **Verify** shimmer appears for <200ms (indicates fetching in progress)
+* **Verify** no console errors or warnings during load
+* **Verify** Chrome DevTools CPU profiler shows no excessive re-renders
+* **Verify** Network tab shows single query (not redundant fetches)
+* **Verify** 7-day, 24-hour, and custom date ranges all load quickly
+* **Verify** works on desktop, tablet, mobile
+* **Verify** regression doesn't reoccur (add performance test)
+* **Verify** documentation updated if behavior changed
+```
+
+### Key Annotations
+
+✅ **Bug Format:** No "AS/WANT/SO THAT" - focus on problem description
+
+✅ **Symptoms Section:** Clear repro steps help developers understand the issue
+
+✅ **Root Cause Reference:** Links to potentially related commit/ticket
+
+✅ **Technical Guidance:** Performance debugging hints (profiler, cache, network)
+
+✅ **Priority P0:** Critical/blocking issue
+
+---
+
+## Example 5: Spike (Investigation Task)
+
+### File: 942-subscription-spike.md
+
+```yaml
+---
+documentType: spike
+title: "APM-R: BE: Data Layer: GraphQL Subscription Architecture Spike"
+description: "Investigate GraphQL subscription patterns and recommend architecture for real-time data updates"
+milestone: Jan2026
+priority: P1
+storyPoints: 3
+labels: [apm-r, backend, spike, architecture]
+createdDate: 2025-12-06
+exportedDate: null
+
+jira-ticketId: null
+jira-url: null
+jira-parent: null
+jira-related: [DAPM-1168]
+jira-blocking: [DAPM-1500]
+jira-blockedBy: []
+jira-fixVersion: null
+jira-internalNotes: "Output: Decision doc on subscription pattern"
+
+framework-documentation: "@apm-r-be/docs/architecture-decisions.md"
+framework-milestone: "backlog/milestones/Jan2026.md"
+framework-technicalGuides:
+  - "@apm-r-be/docs/graphql-api.md"
+  - "@apm-r-be/docs/authentication.md"
+framework-relatedLocal: ["ai/context/technical-advanced.md"]
+---
+
+# APM-R: BE: Data Layer: GraphQL Subscription Architecture Spike
+
+---
+
+## Description
+
+**Context:**
+
+Real-time data updates are becoming important for user experience. We need to move beyond polling to push-based subscriptions. Before implementing, we should investigate:
+
+* Competing subscription architectures (Apollo subscriptions vs. custom WebSocket vs. Server-Sent Events)
+* Complexity vs. benefit trade-offs
+* Integration with our existing authentication and authorization
+* Performance implications at scale
+
+**Research Questions:**
+
+* Which pattern best matches our tech stack (NestJS, GraphQL, Redis)?
+* How do we handle authentication + reconnection + cleanup?
+* What's the overhead per connected client?
+* Can we implement in 1 sprint vs. 2-3 sprints?
+
+**Technical Notes:**
+
+* Apollo Client already used on frontend (familiar pattern)
+* Redis available for pub/sub coordination
+* WebSocket support built into NestJS
+* Study existing implementations in similar systems
+
+---
+
+## Acceptance Criteria
+
+* **Verify** spike document completed with architecture recommendation
+* **Verify** comparison of 3+ subscription patterns with pros/cons
+* **Verify** authentication + reconnection flow designed
+* **Verify** performance estimates provided (client connections, memory, CPU)
+* **Verify** implementation effort estimated (hours/points)
+* **Verify** decision doc linked from DAPM-1168 (parent epic)
+* **Verify** recommendation is actionable (team can implement without further investigation)
+* **Verify** documentation added to decision log
+```
+
+### Key Annotations
+
+✅ **Spike Purpose:** Investigation and learning, not implementation
+
+✅ **Research Questions:** Clear objectives for the spike
+
+✅ **Output Focused:** Acceptance criteria focus on deliverables (decision doc, estimates)
+
+✅ **Unblocks Future Work:** jira-blocking references follow-up story (DAPM-1500) that depends on this decision
+
+---
+
+## Comparison: Good vs. Bad Examples
+
+### GOOD Story: Clear, Specific, Actionable
+
+```markdown
+# APM-R: FE: Dashboard: Add Export Button
+
+---
+
+## Description
+
+**Context:**
+
+Users frequently request CSV export of dashboard data for external analysis. This adds export functionality to reduce manual workarounds. Export will include all visible cards' data in table format.
+
+**Requirements:**
+
+* Add Export button to dashboard toolbar
+* Export visible card data to CSV format
+* Include column headers and timestamps
+* Show success/error toast after export
+
+**Technical Notes:**
+
+* Use papaparse library (already available)
+* Follow existing export pattern in AssetList component
+* CSV file naming: dashboard-{YYYY-MM-DD}-{HH-mm}.csv
+
+---
+
+## Acceptance Criteria
+
+* **Verify** Export button appears in dashboard toolbar
+* **Verify** CSV contains all visible card data
+* **Verify** Column headers properly labeled
+* **Verify** File downloads with correct naming format
+* **Verify** Success toast shown after download
+* **Verify** Error toast shown if export fails
+* **Verify** Works on Firefox, Chrome, Safari
+* **Verify** File opens correctly in Excel/Google Sheets
+* **Verify** Documentation updated
+```
+
+### BAD Story: Vague, Verbose, Unmeasurable
+
+```markdown
+# Add Export Functionality
+
+---
+
+## Description
+
+In today's modern business environment, users need flexibility in how they consume and analyze data. Our dashboard should provide comprehensive export capabilities to ensure data accessibility and usability across different tools and platforms.
+
+**Requirements:**
+
+* Make data exportable
+* Ensure data quality
+* Handle edge cases
+* Maintain performance
+* Support multiple formats
+* Ensure compatibility
+
+**Technical Notes:**
+
+We should use best practices and ensure the implementation is robust and well-tested.
+
+---
+
+## Acceptance Criteria
+
+* **Verify** Export works
+* **Verify** Data is correct
+* **Verify** Performance is good
+```
+
+**Issues:**
+- Verbose context (academic tone)
+- Vague requirements ("make data exportable")
+- No technical specifics (which export format? which library?)
+- Unmeasurable criteria ("performance is good")
+- Way too short (11 lines)
+
+---
+
+## Common Mistakes to Avoid
+
+1. ❌ **Metadata in body:** Never repeat priority/points in the description
+2. ❌ **Code snippets:** Reference patterns, don't paste code
+3. ❌ **### headers in body:** Use bold labels only
+4. ❌ **Bullet points in Context:** Write as paragraphs
+5. ❌ **Vague criteria:** "Make it work" vs. "Verify response time <100ms"
+6. ❌ **Step-by-step instructions:** Trust developers to figure out HOW
+7. ❌ **Missing YAML fields:** All jira-* and framework-* fields required
+8. ❌ **Nested YAML objects:** Flat structure only (jira-field, not jira.field)
+9. ❌ **Local file links in body:** Put them in framework-relatedLocal YAML field
+10. ❌ **Jira URL shortcuts:** Use full URL, not just DAPM-1234