Product Functionality Documentation Strategy

Status: Deferred from Session 143 — ready to action
Origin: docs/continuation-prompts/continuation-prompt-kh-s143.md deferred items
Purpose: Define how we systematically document the 7 functional areas in docs/product-functionality/

1. Why This Track Exists

All 7 functional areas in docs/product-functionality/ are currently Pending:

Area	Status
`search/`	Pending
`content-management/`	Pending
`bid-management/`	Pending
`quality-governance/`	Pending
`knowledge-organisation/`	Pending
`ai-integration/`	Pending
`administration/`	Pending

The system is now sufficiently mature (143 sessions, 8,416 tests, 39 tables, 38 MCP tools) that the absence of functional documentation creates real friction:

Client onboarding — docs/client-documentation/ contains real client artefacts (Platform Overview, Claude Integration Guide) but they drift from the codebase without a grounded source of truth.
Cross-agent context — each new session must re-derive system behaviour from the codebase because no authoritative functional reference exists.
AI/Prompt Engineering track — the AI touchpoint strategy (docs/reference/ai-touchpoint-map-and-improvement-strategy.md) depends on knowing what each AI touchpoint actually does. Functional docs provide that foundation.

2. Active Parallel Workstreams — Sequencing Constraint

Two workstreams are running in parallel with this documentation track. They will change the codebase in ways that make certain areas immediately stale if documented now:

Workstream	Areas to Defer
SI Phase 1d (MCP tools, Intelligence MCP App, E2E)	Intelligence section of `knowledge-organisation/`, MCP tool extensions in `ai-integration/`
AI/PE Phase 1 (Evaluation Foundation — gold standards, eval runners, regression infra)	`ai-integration/` in full

Rule: Do not document a functional area while it is actively being built. Document it after the relevant workstream phase is complete and committed.

3. Source Materials Already Available

Do not re-derive facts from scratch. Read these before authoring any area:

Document	Path	Purpose
State of the Product (v2.28)	`docs/reference/state-of-the-product.md`	Authoritative “what is actually built” reference
Schema Quick Reference	`docs/reference/SCHEMA-QUICK-REFERENCE.md`	All 39 tables, columns, RLS, RPC functions
Codebase Stats	`docs/generated/codebase-stats.md`	Current counts (routes, components, hooks, tools)
MCP Inventory	`docs/generated/mcp-inventory.md`	All 38 tools, 11 resources, 5 prompts with signatures
AI Integration Layers	`docs/reference/ai-integration-layers.md`	5-layer AI architecture
Classification Prompt	`docs/reference/classification-prompt.md`	Domain taxonomy and classification rules
AI Touchpoint Map	`docs/reference/ai-touchpoint-map-and-improvement-strategy.md`	All 18 AI touchpoints across TS/Python pipelines
Design System	`docs/design/warm-meridian-implementation-spec.md`	Semantic tokens, OKLCH colour system, components

4. Four-Phase Process Per Functional Area

Each area follows four phases. Run them sequentially — never skip Phase 3.

Phase 1 — Deep Research (Empirical, No Writing)

A research agent reads the actual codebase for the target area. Output: a research-notes.md scratch file. Do not write final docs in this phase.

What to read:

All API routes under the relevant directory (e.g. /app/api/items/ for content-management)
Key components, hooks, and lib modules (cross-reference docs/generated/codebase-stats.md)
Database tables and RLS policies for the area (use Supabase MCP list_tables, execute_sql)
MCP tools that surface this area (from docs/generated/mcp-inventory.md)
Relevant section of docs/reference/state-of-the-product.md — Section 5 (Feature State)
Existing tests that describe expected behaviour (__tests__/ — they are ground truth)

Output format (research-notes.md):

1
# Research Notes — [Area]
2
## API Routes (verified)
3
## Database Tables & Key Columns
4
## Key Components & Hooks
5
## MCP Tool Exposure
6
## Known Limitations & Rough Edges
7
## Open Questions

Save to /tmp/research-notes-[area].md — not committed.

Phase 2 — Draft (From Research Notes Only)

A writing agent uses ONLY the research-notes.md and directly verified codebase facts. It produces three documents per area using the templates in docs/product-functionality/_templates/:

Template	Output File	When
`user-journeys.template.md`	`[area]/user-journeys.md`	Always
`workflows.template.md`	`[area]/workflows.md`	When state machines or automation exist
`technical.template.md`	`[area]/technical.md`	Always

Writing rules:

UK English throughout. DD/MM/YYYY. “organisation” not “organization.”
Do not hardcode volatile counts (use docs/generated/ references or queries instead)
Note limitations honestly — every feature has rough edges
If uncertain about a fact, mark it [VERIFY] rather than guessing
Max ~500 lines per file. Split if larger.

Phase 3 — Adversarial Verification

A separate agent (or strict self-review phase) takes the Phase 2 draft and actively tries to prove it wrong. For every factual claim:

Does this API route actually exist? (ls app/api/... or grep_search)
Is this DB column name correct? (check schema, not state-of-the-product — it may lag)
Is this MCP tool name current? (check docs/generated/mcp-inventory.md or lib/mcp/tools/)
Does this component exist with this name? (find components/ -name "...")
Is this behaviour actually tested? (find the test — if there’s no test, flag it)

Output: a verification report listing:

✅ Verified claims (count)
❌ Contradictions (with correction)
⚠️ Unverifiable claims marked [VERIFY]

Apply all corrections before Phase 4.

Phase 4 — Finalise and Sync

Apply all Phase 3 corrections to the draft files
Save finalised docs to docs/product-functionality/[area]/
Update the status table in docs/product-functionality/README.md
If the area has MCP-facing exposure, check whether docs/client-documentation/Knowledge Hub — Claude Integration Guide.md needs updating
If the area significantly changes client understanding of the product, flag docs/client-documentation/Knowledge Hub — Platform Overview.md for a follow-up sync session

5. Recommended Area Sequence (Stability-First)

Do not document in impact order. Document in stability order — areas that are not changing come first, so docs are useful immediately without risk of immediate obsolescence.

Tier 1 — Document Now (Stable, not touched by SI or PE)

These areas have been stable since approximately S112-S115:

Priority	Area	Rationale
1	`quality-governance/`	Stable since S114. Bridges, verification, review cadence — mature.
2	`search/`	Consolidated and closed since S111-S113. Well-bounded.
3	`administration/`	Settings, roles, cron, notifications. Unchanged for many sessions.
4	`bid-management/`	State machine, 3-pass drafting, DOCX export. Core is stable.

Continuation prompt for Tier 1: docs/continuation-prompts/continuation-prompt-kh-doc-track-1.md

Tier 2 — Document Now, Flag One Section (Mostly Stable)

Priority	Area	Note
5	`content-management/`	Stable. Source document diff at Phase 4 complete. Safe to document.
6	`knowledge-organisation/`	Document KB org, taxonomy, entity graph, guides, coverage now. Mark the Sector Intelligence workspace subsection `[PENDING — SI Phase 1d]` and defer it.

Tier 3 — Defer Until Workstreams Settle

Priority	Area	Defer Until
7	`ai-integration/`	After AI/PE Phase 1 completes. Documenting now means rewriting once eval infrastructure lands.

6. Session-Dated Versioning Convention

Every doc must carry a header so staleness is explicit rather than hidden:

1
> **Last verified:** Session NNN (DD Month YYYY) **Pending updates:** [describe
2
>
3
> > what is expected to change, or "None — stable area"]

When a parallel workstream session changes a feature covered by an existing doc, the /update-docs skill will automatically:

Add an ## Updates — Session NNN addendum to the affected doc
Update the Last verified header
Mark sections needing fuller review with [NEEDS REVIEW — updated S{NNN}]

A full rewrite of the affected section is then scheduled in the next dedicated documentation session.

7. Agent Allocation for Parallel Execution

Multiple areas can be researched in parallel (Phase 1 is read-only). Drafting and verification must be sequential per area to prevent file ownership conflicts.

Recommended parallel grouping for Tier 1:

1
Wave 1 (Phase 1 — parallel research agents):
2
  Agent A — quality-governance/
3
  Agent B — search/ + administration/ (small enough to bundle)
4
  Agent C — bid-management/
5

6
Wave 2 (Liam reviews research notes before drafting begins):
7

8
Wave 3 (Phase 2+3 — sequential per area, can run concurrently across areas):
9
  Agent A — Draft + verify quality-governance/
10
  Agent B — Draft + verify search/ and administration/
11
  Agent C — Draft + verify bid-management/
12

13
Wave 4:
14
  Phase 4 finalisation + /update-docs + /handoff

Use isolation: worktree (per CLAUDE.md) when agents touch the same files.

8. Continuation Prompt for Starting This Track

The ready-to-use continuation prompt for Tier 1 (stable areas) is:

docs/continuation-prompts/continuation-prompt-kh-doc-track-1.md

Copy its content into a new session in the knowledge-hub repository. It covers quality-governance/, search/, administration/, and bid-management/ across 6 work packages (3 research + 3 draft/verify).

For Tier 2 and Tier 3 areas, a new continuation prompt will be generated via /handoff at the end of the Tier 1 session, once actual session state is known.

9. Client Documentation Sync Protocol

Once 3+ functional areas are documented, run a dedicated sync session:

Read all completed docs/product-functionality/[area]/ files
Cross-reference against docs/client-documentation/Knowledge Hub — Platform Overview.md and Knowledge Hub — Claude Integration Guide.md
Identify stale claims, missing features, and outdated tool descriptions
Update client docs, adversarially verify, commit

Do not update client docs piecemeal after each area — wait for a critical mass so the sync is coherent and complete.

10. Quality Gates

Before marking any area “Complete” in the README status table:

All three template documents produced (user-journeys.md, technical.md, and workflows.md if applicable)
Adversarial verification passed (all [VERIFY] items resolved or explicitly accepted)
API route names verified against actual codebase
Table/column names verified against Supabase schema (not just state-of-the-product)
MCP tool names verified against docs/generated/mcp-inventory.md
README status table updated
Limitation section honest and non-empty (every feature has rough edges)