DOCS-02] Use AI to generate and maintain living documentation (the least-used AI capability)

[paruff]

[DOCS-02] Use AI to generate and maintain living documentation (the least-used AI capability)

GitHub Issue Title: [DOCS-02] Use AI to generate and maintain living documentation

Field	Value
Phase	Phase 6 — Code Quality
DORA 2025 Source	2025 DORA report: documentation and requirements analysis are the least common AI use cases despite being high-value; Scrum.org analysis: “AI is still primarily seen as a coding assistant, not a thinking partner”
Labels	documentation, ai-ops, p2-important, effort-small
Effort	Small (< 1 day initial; maintained by Copilot on each merge)
Assignee	🤖 Copilot
Prerequisites	AIOPS-04 (prompt library), DATA-01 (unified types), QA-05 (JSDoc)

---

Why the 2025 DORA Report Flags This as a Gap

The 2025 DORA State of AI-assisted Software Development survey showed a significant imbalance in how developers use AI:

Most common AI uses (coding):

• Writing new code
• Modifying existing code
• Debugging
• Generating tests

Least common AI uses (thinking):

• Requirements analysis
• Documentation
• Planning work
• Architecture insights

The Scrum.org analysis of the 2025 report concludes: “AI is still primarily seen as a coding assistant, not a thinking partner. That will change — but only when teams learn how to trust and verify AI outputs.”

For Goald, the implication is concrete: there are several high-value documentation artifacts that can be generated and kept current by Copilot at near-zero marginal cost, but which don’t currently exist. Undocumented code forces every contributor (including Copilot itself) to reverse-engineer intent from implementation — which is exactly the fragile, unreliable context that produces poor AI output.

---

The Three Living Documents This Issue Creates

1. API Surface Document (docs/API_SURFACE.md)

A Copilot-generated, Copilot-maintained summary of every public function in src/services/ and src/utils/. Regenerated whenever these files change.

Format per function:

### goalService.createGoal(userId, goalData)
**Purpose:** Creates a new goal document in Firestore under users/{userId}/goals
**Parameters:** userId: string, goalData: Partial<Goal>
**Returns:** Promise<string> — the new document ID
**Side effects:** Writes to Firestore; does not update userStats
**Error cases:** throws ValidationError if goalData.targetAmount <= 0

This document gives Copilot the context it needs to use service functions correctly without reading the implementation.

2. Known Limitations Register (docs/KNOWN_LIMITATIONS.md)

A human-curated list of technical debt, architectural compromises, and known bugs that every contributor needs to be aware of. Copilot should reference this before generating code in affected areas.

Initial entries from codebase audit:

• Deposit balance update uses React state (race condition — see SEC-05)
• Streak calculation is inline in DepositScreen (should be in utils — see TEST-03)
• No retry logic on Firestore writes (silently fails on network error)
• Push token registration not wired up (see PROD-06)

3. Change Impact Map (docs/CHANGE_IMPACT_MAP.md)

A simple table showing which files are affected when key data structures change. Copilot cannot reason about cross-file impact without this.

Example:

| If you change... | You must also update... |
|---|---|
| Goal type in src/types/index.ts | goalService.ts, GoalCard.tsx, GoalDetailScreen.tsx, TEST-01 tests |
| UserStats type | badgeService.ts, streakCalculator.ts, DashboardScreen.tsx |
| Deposit type | depositService.ts, DepositScreen.tsx, GoalDetailScreen.tsx |

---

Acceptance Criteria

API Surface Document

• docs/API_SURFACE.md created with all public functions in src/services/ and src/utils/ documented in the format above
• GitHub Actions workflow updated: when any file in src/services/ or src/utils/ is changed in a PR, a bot comment is posted: “⚠️ Service/utils changed — remember to update docs/API_SURFACE.md”
• docs/PROMPT_LIBRARY.md (AIOPS-04) updated with an “Update API Surface” prompt template

Known Limitations Register

• docs/KNOWN_LIMITATIONS.md created with at least 5 entries from the codebase audit
• Format: | Area | Limitation | Related Issue | Severity |
• .github/copilot-instructions.md updated: “Before generating code, check docs/KNOWN_LIMITATIONS.md for known issues in the relevant area”

Change Impact Map

• docs/CHANGE_IMPACT_MAP.md created with entries for all three core types (Goal, Deposit, UserStats)
• Updated as part of DATA-01 if unified types are introduced

Documentation as Part of the Golden Path (connects to PLAT-02)

• docs/GOLDEN_PATH.md updated: Step 10 includes “Update docs/API_SURFACE.md if any service or util function was added or changed”

---

Files to Create / Change

• docs/API_SURFACE.md (create — Copilot generates first version)
• docs/KNOWN_LIMITATIONS.md (create — human seeds, Copilot maintains)
• docs/CHANGE_IMPACT_MAP.md (create — Copilot generates from types)
• .github/workflows/ci-quality.yml — add service/utils change reminder comment
• .github/copilot-instructions.md — add KNOWN_LIMITATIONS reference
• docs/GOLDEN_PATH.md — add documentation update to Step 10