Word.md - Requirements Precise Enough to Test

# Word.md - Business and Product Context
<!-- Product vision, user personas, requirements, and stakeholder context -->
<!-- Bridges the gap between business needs and technical implementation -->
<!-- Last updated: 2026-08-26 -->

## Product Vision

**Product**: Beacon - Team Feedback and Performance Platform
**Tagline**: "See what matters. Grow what counts."
**Company**: NorthStar People (Series A, 42 employees)
**Target Market**: Mid-market companies (200-2,000 employees) using modern HR tech stacks

### Vision Statement

Beacon replaces the annual performance review with continuous, lightweight feedback loops that give managers real-time visibility into team health and give employees a clear path for growth. We believe performance management should feel like a conversation, not a courtroom.

### Problem We Solve

Traditional performance reviews fail everyone involved. Managers spend 15+ hours per cycle writing reviews based on recency bias. Employees receive feedback too late to act on it. HR teams spend months coordinating a process that few of its participants believe changed any outcome. Meanwhile, high performers leave because they do not feel recognized, and struggling employees do not get the coaching they need until it is too late.

> **Replace this callout with your own evidence.** A problem statement earns its place when it carries a number, a named source, and a date: `[NN]% of [population] report [outcome] ([Source], [Year])`. Do not paste a figure you have not read at the source, and re-check it whenever you revise this document - a statistic with no date attached is unfalsifiable, and a coding agent reading this spec will treat every claim in it as a settled requirement.

### How We Are Different

1. **Micro-feedback over mega-reviews** - 2-minute weekly check-ins replace quarterly review documents
2. **AI-powered insights, not AI-written reviews** - Our AI surfaces patterns and flags risks, but humans write the words
3. **Manager coaching built in** - The platform coaches managers on how to give better feedback, not just where to type it
4. **Integrates where work happens** - Slack and Teams integrations mean feedback happens in-context, not in a separate tool

### Business Model

- **Pricing**: Per-seat SaaS, $12/user/month (annual) or $15/user/month (monthly)
- **Target contract**: 200-500 seats, $28,800-$72,000 ARR per customer
- **Sales motion**: Product-led growth (free trial for teams under 25) + enterprise sales for 500+ seats
- **Current traction**: 127 paying customers, $1.8M ARR, 94% gross retention

## User Personas

### Persona 1: Maya - Engineering Manager
**Demographics**: 34 years old, San Francisco, manages a team of 8 engineers
**Tech savviness**: High - uses 15+ tools daily, automates everything she can
**Goals**:
- Give meaningful, timely feedback without spending her entire Friday writing reviews
- Identify when a team member is disengaged before they hand in their notice
- Build a culture of recognition without it feeling forced or performative
- Have data to back up promotion cases instead of relying on anecdotes

**Pain Points**:
- Current tool (Lattice) requires 20+ minutes per person per review cycle
- She forgets specific examples by the time review season comes around
- No way to see trends across her team - is morale improving or declining?
- Her skip-level manager asks for "performance data" but all she has are vibes

**Quote**: "I want to be a great manager, but the tools we use make it feel like paperwork instead of people work."

### Persona 2: Carlos - HR Director
**Demographics**: 41 years old, Austin, oversees people operations for 600-person company
**Tech savviness**: Medium - comfortable with SaaS tools but not a power user
**Goals**:
- Reduce voluntary turnover from 22% to under 15%
- Ensure performance conversations happen consistently across all departments
- Generate reports for the executive team that show ROI of people programs
- Maintain compliance with documentation requirements without drowning in paperwork

**Pain Points**:
- Manager compliance with review deadlines is under 60%
- Different departments use wildly different standards for ratings
- Cannot connect performance data to retention outcomes
- The C-suite sees HR tools as cost centers, not strategic investments

**Quote**: "I need a system that managers actually want to use. If they do not use it, it does not matter how good the features are."

### Persona 3: Priya - Individual Contributor
**Demographics**: 27 years old, remote (Chicago), senior product designer, 3 years at company
**Tech savviness**: High - design tools expert, uses AI tools daily
**Goals**:
- Understand what she needs to do to get promoted to Staff Designer
- Receive regular feedback, not just during review season
- Feel recognized for her contributions, especially cross-team work that her manager does not see
- Build a portfolio of accomplishments for career conversations

**Pain Points**:
- Only gets formal feedback twice a year - too infrequent to course-correct
- Her manager is remote and often does not see her day-to-day impact
- Peer feedback is only collected during official review cycles
- No clear competency framework - promotion criteria feel arbitrary

**Quote**: "I do great work but I have no idea if my manager knows that. I should not have to self-promote just to get recognized."

## Feature Requirements

### Epic: Weekly Check-ins (P0 - Core Feature)

#### Story 1: Manager Sends Weekly Check-in
**As a** manager
**I want** to send a 3-question check-in to my team each week
**So that** I can spot trends and have data for coaching conversations

**Acceptance Criteria**:
- [ ] Manager can customize the 3 check-in questions from a library of 20+ templates
- [ ] Check-in is sent automatically every Monday at 9 AM in the employee's timezone
- [ ] Employees receive the check-in in Slack/Teams with a direct reply option
- [ ] Responses are visible to the manager within 5 seconds of submission
- [ ] Dashboard lists this week's response rate and names who has not responded yet
- [ ] Manager can add a private note after reading each response

**Priority**: P0 (Must Have)
**Effort**: L (3 sprints)
**Dependencies**: Slack integration, notification service, sentiment analysis API

#### Story 2: Employee Responds to Check-in
**As an** employee
**I want** to respond to my weekly check-in in under 2 minutes
**So that** my manager has visibility into how I am doing without lengthy meetings

**Acceptance Criteria**:
- [ ] Response UI supports both free-text and emoji/scale responses
- [ ] Employee can respond directly in Slack or in the web app
- [ ] Response is private between employee and manager by default
- [ ] Employee can optionally share a response as public recognition
- [ ] System shows a streak counter to encourage consistent participation
- [ ] Late responses (after Wednesday) are accepted but flagged as late

**Priority**: P0 (Must Have)
**Effort**: M (2 sprints)

### Epic: AI Insights Dashboard (P1 - Differentiator)

#### Story 3: Sentiment Trend Analysis
**As a** manager
**I want** to see AI-generated insights about my team's sentiment trends
**So that** I can proactively address morale issues before they become attrition

**Acceptance Criteria**:
- [ ] Dashboard shows sentiment score (1-10) per team member, trended over 12 weeks
- [ ] AI flags significant drops (>2 points in 2 weeks) with a "needs attention" badge
- [ ] Insights include suggested conversation starters based on the sentiment pattern
- [ ] Data is aggregated and anonymized for teams of 5+ when viewed by skip-level managers
- [ ] AI never fabricates feedback - every insight links back to source check-in responses

**Priority**: P1 (Should Have)
**Effort**: XL (4 sprints)
**Dependencies**: ML model training, privacy review, data aggregation pipeline

#### Story 4: [Recognition Feed]
**As a** [team member]
**I want** [to see and give public recognition to peers]
**So that** [positive contributions are visible across the organization]

**Acceptance Criteria**:
- [ ] [Users can give recognition with a message and optional company value tag]
- [ ] [Feed is visible to the entire organization with filtering by team/value]
- [ ] [Managers receive a weekly digest of recognition given to their reports]
- [ ] [Recognition data feeds into the performance review summary]

**Priority**: P1 (Should Have)
**Effort**: M (2 sprints)

### Epic: [Performance Review Cycle] (P1)

#### Story 5: [Automated Review Assembly]
**As a** [manager]
**I want** [the system to pre-populate review drafts from weekly check-in data]
**So that** [I spend 10 minutes refining a review instead of 45 minutes writing one from scratch]

**Acceptance Criteria**:
- [ ] [System generates a draft review pulling quotes and themes from the last 6 months of check-ins]
- [ ] [Draft includes recognition received, goals progress, and sentiment trends]
- [ ] [Manager can edit, add to, or rewrite any section before submitting]
- [ ] [Clear labeling distinguishes AI-assembled content from manager-written content]

**Priority**: P1 (Should Have)
**Effort**: L (3 sprints)
**Dependencies**: [AI summary generation, check-in data model, review template system]

## Requirements as Spec

Treat this document as the primary artifact and the code as a regenerable output of it. When a requirement changes, you edit the spec first and revise or regenerate the affected code second - never the other way around. A spec that can carry that loop defines six things, and this document is laid out to hold all six:

| Spec element | Where it lives in this document |
|--------------|---------------------------------|
| Outcomes | Product Vision, Success Metrics |
| Scope boundaries | Feature Requirements (epics and priorities), Metrics We Will NOT Optimize For |
| Constraints | Business Model, Stakeholder Map (Consulted) |
| Prior decisions | How We Are Different, Domain Glossary |
| Task breakdown | Stories, with effort and dependencies |
| Verification criteria | Acceptance criteria, plus the Verification Criteria section below |

A missing element does not stay missing. It gets filled in by whoever implements the story - silently, inconsistently, and without a record of the choice.

### Vague vs Machine-Checkable Acceptance Criteria

An acceptance criterion is machine-checkable when it names three things: the **input**, the **observable output**, and the **tolerance**. With all three, a developer can write a test from it and an agent can verify its own work against it. Missing one, it is a wish.

| Vague | Machine-checkable |
|-------|-------------------|
| User can log in | User submits a valid email and password, receives a JWT in the response body, and lands on `/dashboard` in under 2 seconds |
| The dashboard should feel fast | Dashboard first contentful paint is under 1.5 seconds on a throttled mobile connection with 12 weeks of seeded check-in data |
| Sentiment scores are accurate | Sentiment score is an integer from 1 to 10; re-scoring an unchanged response returns the same value; every score cites the response IDs it was derived from |
| Handle bad input gracefully | Submitting an empty check-in response returns HTTP 422 with error code `response_required` and creates no row |
| Managers get notified | A manager with one or more unread responses receives exactly one digest per day, at 9 AM in the manager's own timezone |

Note what the right-hand column does not do: it does not describe the interface. "Click the blue Save button in the top right" pins the criterion to a layout that will be redesigned. "Submitting the check-in form persists the response and returns its ID" survives every redesign, and can still be tested.

### AI Output Quality Is a Requirements Test

The fastest ambiguity detector available to a product team is to hand a story to a coding agent and read what comes back. When an agent builds the wrong thing, the usual cause is not that it misread the story - it is that the story permitted more than one reading and the agent picked one. Treat a wrong build as a defect report against the spec.

Run it deliberately before a story enters a sprint:

1. Give an agent the story, its acceptance criteria, and the Domain Glossary - nothing else.
2. Read the output against your intent, not against its code quality.
3. For every divergence, find the sentence that permitted it and rewrite that sentence.
4. Repeat until the output matches intent on the first pass.

The same ambiguity that misleads an agent in thirty seconds misleads a new developer over three days, so the loop is worth running even on teams that write all their own code. Two failure modes it surfaces reliably:

- **Undefined terms.** "Notify the account owner" produces different code depending on whether "account" means the billing entity or an individual user. That is why the Domain Glossary below is part of the spec, not a nice-to-have appendix.
- **Unstated defaults.** "Send the check-in weekly" leaves the day, the hour, the timezone, the retry behavior, and what happens on a company holiday to whoever writes the code first.

## Verification Criteria

Acceptance criteria prove a story works. Verification criteria prove the release is correct, and they are written before implementation starts rather than assembled afterward. Each one names the check and who runs it.

### Functional Verification

| Criterion | How it is verified | Owner |
|-----------|--------------------|-------|
| Every P0 acceptance criterion has at least one automated test tagged with its story ID | CI test report, grouped by story ID | Engineering |
| A check-in response is visible only to its author and that author's direct manager by default | Integration suite covering every role in the permission matrix | Engineering |
| Every AI-surfaced insight cites the source responses it was derived from | Automated check: an insight with zero source IDs fails to render | Engineering |
| No AI-drafted text reaches an employee without a human editing step | Walkthrough of the review-assembly flow, signed off each release | Product |

### Non-Functional Verification

| Criterion | Threshold | How it is verified |
|-----------|-----------|--------------------|
| Check-in submission latency | p95 under 500 ms | Load test at 3x expected peak concurrency |
| Response visible to the manager after submission | Under 5 seconds | End-to-end timing test |
| Accessibility | No WCAG AA violations on the check-in and dashboard flows | Automated audit in CI plus one manual keyboard pass |
| Compliance export completeness | Export contains every field the compliance section requires | Schema diff of the export against the documented field list |

### Sign-Off Gates

- [ ] Legal/Compliance has reviewed every AI-facing feature in this release for bias and privacy risk
- [ ] Security has reviewed handling of PII appearing in free-text responses
- [ ] Every Open Question blocking a P0 story is resolved, with the resolution recorded in this document
- [ ] The Domain Glossary defines every term this release introduces

## Domain Glossary

### Business Terms
- **Check-in**: A short, recurring feedback prompt sent from manager to employee (3 questions, weekly cadence by default)
- **Sentiment score**: A 1-10 numerical rating derived from check-in response content and tone. Uses NLP analysis, not self-reported scores.
- **Recognition**: A public, peer-to-peer acknowledgment tied to a company value. Visible on the organization-wide feed.
- **Review cycle**: A time-bounded period (typically quarterly or semi-annual) during which formal performance reviews are written and delivered.
- **Competency framework**: A structured set of skills and behaviors expected at each career level, used to evaluate performance and guide promotion decisions.
- **Skip-level**: A manager's manager. Skip-level views show aggregated team data, not individual responses.
- **Streak**: Consecutive weeks an employee has responded to their check-in. Used for engagement gamification.

### Technical Terms
- **Pulse API**: The internal API that sends and receives check-in data. Handles Slack/Teams integration routing.
- **Insight Engine**: The ML pipeline that analyzes check-in responses and generates sentiment scores and trend alerts.
- **Review Assembler**: The service that pre-populates performance review drafts from historical check-in data.

## Success Metrics

### North Star Metric
**Manager-to-employee feedback frequency** - Average number of meaningful feedback interactions per manager-employee pair per month. Target: 4+ (currently 0.8 for our target market).

### Key Performance Indicators

| Metric | Current | Q3 Target | Q4 Target |
|--------|---------|-----------|-----------|
| Weekly check-in completion rate | - | 70% | 80% |
| Average time to complete check-in | - | <2 min | <90 sec |
| Manager weekly active usage | - | 65% | 75% |
| Employee NPS | - | 30 | 45 |
| Voluntary attrition (customers using Beacon) | 22% baseline | 19% | 16% |
| Net Revenue Retention | 108% | 115% | 120% |

### Metrics We Will NOT Optimize For
- Number of reviews written (vanity metric - more is not better)
- Average review length (longer reviews are not better reviews)
- Login frequency without corresponding engagement (drive usage, not logins)

## Stakeholder Map

### Decision Makers
- **CEO** ([Name]) - Final say on product strategy and pricing. Cares about market differentiation and ARR growth.
- **VP Product** ([Name]) - Owns the roadmap. Balances customer requests against vision. Weekly sync on priorities.
- **VP Engineering** ([Name]) - Owns technical feasibility and timeline estimates. Raises concerns about tech debt.

### Influencers
- **Head of Customer Success** ([Name]) - Relays customer pain points and churn risks. Largest source of feature requests.
- **Head of Sales** ([Name]) - Provides competitive intelligence. Pushes for features that close deals.
- **Design Lead** ([Name]) - Owns user research and usability. Advocates for simplicity over feature count.

### Consulted
- **Legal/Compliance** - Review all AI features for bias risk and data privacy (GDPR, CCPA)
- **Security Team** - Audit data handling, especially PII in feedback content
- **Customer Advisory Board** - 12 customers who preview features quarterly and provide structured feedback

## Release Plan

Replace each bracketed target with a committed date in `YYYY-MM-DD` form, and move a phase's date only in a commit that says why it moved. A phase is done when its items ship *and* the Verification Criteria for them pass.

### Phase 1: Foundation (Target: [YYYY-MM-DD])
- [ ] Weekly check-in send and respond flow
- [ ] Slack integration (send and respond in-channel)
- [ ] Manager dashboard with response history
- [ ] Basic sentiment scoring
- [ ] Mobile-responsive web app

### Phase 2: Intelligence (Target: [YYYY-MM-DD])
- [ ] AI sentiment trend analysis and alerts
- [ ] Recognition feed with company values
- [ ] Teams integration
- [ ] Manager coaching suggestions
- [ ] Export data for compliance

### Phase 3: Review Reinvention (Target: [YYYY-MM-DD])
- [ ] AI-assembled review drafts
- [ ] Competency framework builder
- [ ] 360-degree feedback collection
- [ ] Calibration tools for HR
- [ ] Analytics API for enterprise customers

## Open Questions

- [ ] Should managers see individual sentiment scores or only team aggregates? (Privacy vs. utility trade-off)
- [ ] How do we handle check-in responses that mention sensitive topics (mental health, harassment)? Need escalation workflow.
- [ ] What is the minimum team size for aggregated skip-level views? (Currently 5, some customers want 3)
- [ ] Do we build our own NLP sentiment model or use a third-party API? Cost vs. accuracy vs. data privacy.
- [ ] Should recognition be tied to monetary rewards (gift cards, bonuses) or keep it non-monetary?