Requirements scattered across Jira tickets, email threads, and meeting notes create ambiguity that costs sprints. Word.md consolidates your user stories, acceptance criteria, and domain glossary into structured markdown that engineers and AI assistants reference as the single source of truth.
Write requirements once in markdown. Engineers read them in their IDE. AI assistants consume them before generating code. Product managers review them in pull requests. Everyone works from the same definition of done.
The gap between what product wants and what engineering builds is a documentation gap. Close it with versioned business context that travels with the code.
Bridge the gap between product vision and engineering execution with structured business context that everyone - humans and AI - can reference.
Define every business term your team uses - "customer" vs "user" vs "account", "order" vs "transaction" vs "purchase". Ambiguous terminology causes bugs. A glossary in markdown eliminates interpretation differences between developers, product, and AI.
Every user story needs acceptance criteria specific enough to write tests from. "User can log in" is vague. "User submits email and password, receives JWT token, gets redirected to /dashboard within 2 seconds" is testable and AI-actionable.
Document the complete flow from user intent to completed action. Include happy paths, error states, and edge cases. AI assistants that understand the full journey generate code that handles transitions correctly.
When product chooses speed over completeness or consistency over flexibility, write it down with reasoning. These trade-off decisions prevent engineers from over-building and help AI assistants make aligned implementation choices.
Document which features are must-have versus nice-to-have, and who decides. Priority context prevents scope creep and helps AI assistants focus generated code on the critical path rather than edge cases.
Requirements evolve. Use markdown headers with dates to track how requirements changed and why. Version history prevents "but I thought we agreed" disputes and helps AI understand which version of reality to code against.
Maintain a section of unresolved questions with owners and deadlines. Visible open questions prevent developers from making assumptions and signal to AI assistants where the specification is intentionally incomplete.
Link business requirements to technical constraints - "real-time notifications require WebSocket support" or "GDPR compliance requires data deletion within 30 days." AI assistants need both business and technical context to generate compliant code.
Requirements written clearly enough for an AI assistant to implement correctly are requirements written clearly enough for any developer to implement correctly. This is the quality bar your business context should meet. If an AI assistant reads your Word.md file and generates code that misses the point, the problem is the documentation, not the AI. Use AI output quality as a feedback signal for your requirements quality.
# 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: YYYY-MM-DD -->
## 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 waste months coordinating a process that 92% of employees say does not improve their performance (Gallup, 2024). 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.
### 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 shows response rates and sentiment trends over the last 12 weeks
- [ ] 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]
## 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
### Phase 1: Foundation (Target: [Date])
- [ ] 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: [Date])
- [ ] 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: [Date])
- [ ] 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?
Business requirements scattered across Jira, emails, and meetings create ambiguity. Word.md consolidates user stories, acceptance criteria, and domain glossaries in markdown. Your AI assistants can reference the single source of truth. Product context becomes infrastructure, not afterthought.
Product decisions need documentation that evolves with understanding. Word.md captures requirements, constraints, and trade-offs in version-controlled markdown. Stakeholders review in pull requests. AI assistants help maintain consistency. Everyone works from the same definition of done.
Your business domain is complex - capture it properly. Word.md documents domain concepts, business rules, and terminology in structured markdown. New team members get instant access. AI assistants understand your business context. Tribal knowledge becomes organizational asset.
"Product success depends on shared understanding. Word.md transforms ephemeral conversations into permanent, versioned context - ensuring that business requirements, stakeholder intentions, and domain knowledge persist throughout the development lifecycle."
Built by product teams who believe requirements are too important to live in disconnected tools.
We are on a mission to help product teams recognize that requirements scattered across Jira, emails, and meetings create ambiguity and delay. Business context deserves the same rigor as code - versioned, reviewed, and accessible. When requirements live in .md files alongside your code, product and engineering move at the same velocity.
Our goal is to demonstrate that product documentation can be infrastructure. User stories, acceptance criteria, and domain glossaries in markdown become the source of truth that both humans and AI reference. This is how aligned teams ship faster - shared understanding captured in shared format.
LLMs parse markdown better than any other format. Fewer tokens, cleaner structure, better results.
Context evolves with code. Git tracks changes, PRs enable review, history preserves decisions.
No special tools needed. Plain text that works everywhere. Documentation humans actually read.
Need help structuring product requirements? Want to discuss business context strategies? We're happy to chat.