SynergyPlan Feature Documentation Standard

Advice report on how to structure feature documentation so that any team member or AI agent can understand, contribute to, and implement features consistently.

The Problem

Our current feature notes are a wall of mixed information — functional descriptions, technical details, file paths, and color codes all crammed into one paragraph. This makes it:

Hard for non-technical team members to understand what a feature does
Hard for developers to find the technical details they need
Hard for AI agents to fill in sections without overwriting each other
Impossible for new team members to get up to speed

Research: What Top Teams Do

Stripe — Strategy Memos

Stripe documents features as "strategy memos" that focus on the why before the what. Engineers, PMs, and partnerships all write documents. The emphasis is on getting to the right answer through writing.

Basecamp — Shape Up Pitches

Every feature starts with 5 ingredients: Problem, Appetite (how much time we're willing to spend), Solution, Rabbit Holes (risks to call out), and No-Gos (what we're explicitly not building). Problem and solution are always presented together.

Linear — Taste-Driven with Minimal Process

Linear keeps documentation lean. The team collectively thinks about the product. Documentation exists to communicate, not to satisfy a process.

Key Insight

The best teams separate problem from solution, document what they're NOT building, and tailor information to the audience reading it.

Our Standard: Layered Feature Documentation

Every feature in SynergyPlan gets a structured document with distinct layers. Each layer serves a different audience and can be filled independently by different agents or team members without overwriting each other.

The Layers

┌─────────────────────────────────────┐
│  1. CONTEXT        (Everyone)       │  Why does this feature exist?
├─────────────────────────────────────┤
│  2. FUNCTIONAL     (PM / User)      │  What does it do? (ELI18)
├─────────────────────────────────────┤
│  3. UX & DESIGN    (Designer)       │  What does it look/feel like?
├─────────────────────────────────────┤
│  4. TECHNICAL      (Developer)      │  How is it built?
├─────────────────────────────────────┤
│  5. STATUS         (Everyone)       │  Where are we now?
└─────────────────────────────────────┘

Layer 1: Context (for Everyone)

Answers: Why does this feature exist? What problem does it solve?

## Context

**Problem:** Users can't quickly find specific verses when searching, because results
are displayed as a flat list with no visual hierarchy.

**Solution:** Group search results by book with headers and counts, so users can
quickly scan which books contain matches and jump to the relevant section.

**Not included:** Full-text preview of surrounding verses. That's a separate feature.

Rules:

One paragraph max per section
No technical jargon
Must include what we're NOT building (scope boundary)
Anyone should understand this — your mom, your investor, your new hire

Layer 2: Functional (for PMs and Users)

Answers: What does the user experience? Explain it like I'm 18.

## Functional

When you search for a word, the results appear grouped under book headers (e.g., "Genesis — 12 results", "Psalms — 8 results"). Each group can be collapsed or expanded. The total result count shows at the top.

**User flow:**
1. User types a search query
2. Results load, grouped by book in biblical order
3. Each book header shows the book name and match count
4. User clicks a header to collapse/expand that group
5. User clicks a result to navigate to that verse

**Edge cases:**
- If all results are in one book, the header still shows (no special case)
- Empty search shows nothing (no "search for something" prompt needed)

Rules:

Written in plain language, as if explaining to a smart 18-year-old
Describe the user flow step by step
Include edge cases
No code, no file paths, no DB schemas
This is what QA tests against

Layer 3: UX & Design (for Designers)

Answers: What does it look and feel like?

## UX & Design

**Visual:**
- Book headers: bold, 14px, with result count in gray to the right
- Results indented under headers with left border (2px, --color-accent)
- Collapse/expand: chevron icon rotates 90°

**Colors:**
- Header text: var(--color-text-primary)
- Result count: var(--color-text-secondary)
- Left border: var(--color-accent) (#7dd3fc)

**Responsive:**
- Desktop: full-width results
- Mobile: same layout, touch-friendly headers (min-height 44px)

**Animations:**
- Collapse: 200ms ease-out height transition
- No animation on initial load

**Screenshots:**
![Current search results](/synergyplan/file/screenshot.png)

Rules:

Include specific colors, sizes, spacing
Reference design tokens / CSS variables
Include responsive behavior
Include animations and transitions
Screenshots or mockups when available
This is what the designer reviews

Layer 4: Technical (for Developers)

Answers: How is it built? What do I need to know to implement or modify this?

## Technical

**Data:**
- Query: `searchVerses()` in `apps/web/src/lib/server/queries/search.ts`
- Results include `book_id` — group by this field client-side
- Book names from `BOOK_NAMES` constant in `bible-constants.ts`

**Components:**
- `SearchResults.svelte` — main results container
- `SearchResultGroup.svelte` — collapsible book group (new component)

**API:**
- `GET /api/search?q=term&lang=en` — returns flat array, client groups

**Dependencies:**
- No new dependencies needed
- Reuses existing `ChevronIcon` component

**Files:**
- `apps/web/src/routes/(app)/search/+page.svelte` (modify)
- `apps/web/src/lib/components/search/SearchResultGroup.svelte` (create)

Rules:

DB tables, queries, API endpoints
Component names and file paths
What to create vs what to modify
Dependencies and imports
This is what the developer codes from

Layer 5: Status (for Everyone)

Answers: Where are we right now?

## Status

**Current:** PLANNED
**Milestone:** v1
**Priority:** High — blocks search usability for launch

**History:**
- Existed in BibleGame desktop app (SearchView.cs — grouped results with book headers)
- Not yet ported to web

**Dependencies:**
- Requires: search API (DONE)
- Blocks: nothing

Rules:

Current status and milestone
Why this priority
What existed before (BibleGame reference if applicable)
What depends on this, what this depends on

File Structure

Each feature's documentation lives in a single markdown file at:

projects/[project]/features/[feature-slug]/README.md

The file uses the 5 layers as ## headings. This means:

Each layer can be edited independently
AI agents can target a specific ## section without touching others
The feature detail page can render each layer as a separate card/tab

Additional files in the same folder:

projects/[project]/features/[feature-slug]/
├── README.md           # The 5-layer documentation
├── screenshot.png      # Current state (for DONE features)
├── mockup.png          # Design concept (for PLANNED features)
├── before.png          # What it looked like in BibleGame
└── notes.md            # Freeform notes, meeting minutes, decisions

Agent Guidelines

When an AI agent fills in feature documentation:

Never overwrite other layers. Each layer is independent. If you're filling in the Technical layer, don't touch Functional or UX.
Use the exact headings. ## Context, ## Functional, ## UX & Design, ## Technical, ## Status. Agents search for these headings to find their section.
One agent per layer. Don't have one agent fill everything. Let specialized agents handle their expertise:
- Product agent → Context + Functional
- Design agent → UX & Design
- Code agent → Technical
- Status agent → Status
Screenshots must match reality. If the feature is DONE, the screenshot must show the actual current UI in the correct language and theme. Never use generated/fake screenshots.
Don't invent information. If you don't know something, leave the section empty with a > TODO: [what's needed] note. Wrong information is worse than missing information.
Keep Context and Functional jargon-free. A non-technical team member must be able to read these layers and fully understand what the feature does and why it exists.

How to Populate Features

For existing DONE features:

Context: Why was this built? What problem did it solve?
Functional: What does it actually do? Walk through the user flow.
UX & Design: What does it look like? Take a real screenshot.
Technical: What code powers this? Which files, components, APIs?
Status: Mark DONE, note what milestone, link to BibleGame predecessor if applicable.

For PLANNED features:

Context: Why do we want this? What's the problem?
Functional: What should it do? Step-by-step user flow.
UX & Design: Mockup or description of intended look.
Technical: Proposed approach — which files to create/modify, data needs.
Status: Mark PLANNED, note milestone, any blockers.

For NEEDS_DESIGN features:

Context: What's the idea? (required)
Functional: Rough idea of user flow (if known)
UX & Design: Open questions, inspiration, competitor references
Technical: Leave empty or note constraints
Status: Mark NEEDS_DESIGN, note what design decisions are needed.

Sources

This standard draws from:

Stripe — strategy memo culture, writing as thinking
Basecamp Shape Up — Problem/Appetite/Solution/Rabbit Holes/No-Gos format
Linear — minimal process, taste-driven decisions
Carnegie Mellon SEI — 60-80% of dev cost is rework from poor requirements
OpenAI PRD Template — structured sections for AI-powered documentation