ADR-0004-app-solution-documentation-and-acceptance.md

# ADR-0004: App solution documentation and acceptance criteria

Date: 2026-05-04  
Status: Accepted

## Context

Kompis-managed app projects need a consistent way to document:

- what the solution is meant to do
- which capabilities it must provide
- how success is judged
- how the docs stay current as the project evolves

Without a clear rule, project intent drifts away from implementation and acceptance becomes ambiguous.

## Decision

### 1. Every app project should have solution documentation

Each app/project should maintain project docs that describe:

- the problem it solves
- target users / owners
- core solution capabilities
- constraints and non-goals
- environments and deployment expectations
- acceptance criteria for key capabilities

The exact file names can vary by project, but the information must exist in-repo.

### 2. Acceptance criteria must be explicit and testable

Acceptance criteria should be written so they can be verified.

Good criteria:

- are specific
- are observable
- can be checked manually or by tests
- map to a capability or user outcome

Avoid vague criteria that cannot be checked.

### 3. Documentation must stay in sync with implementation

Project docs should be updated when the solution changes.

Docs must be refreshed when there are meaningful changes to:

- capabilities
- flows
- UI/UX behavior
- environment setup
- acceptance criteria
- constraints or non-goals

### 4. Code changes and doc changes should travel together

When practical, updates to solution capabilities or acceptance criteria should be made in the same work item/commit/PR as the code change.

### 5. Documentation owns the agreed truth

For active projects, the docs in the project repo are the source of truth for current intended behavior.

Chat may help draft or revise them, but it does not replace the repo documentation.

### 6. Governance and review

Kompis should periodically check whether project docs still match reality, especially after:

- feature additions
- environment changes
- customer/company ownership changes
- major bug fixes that alter expected behavior

If docs and behavior diverge, update the docs or raise the mismatch explicitly.

## Consequences

### Positive

- Clearer project scope
- Easier onboarding and handover
- Better alignment between code and intent
- Easier acceptance and verification

### Tradeoffs

- Requires discipline to keep docs current
- Adds small maintenance overhead

## Notes

See also:

- `docs/ADR-0002-app-projects-environments-and-repos.md`
- `docs/ADR-0003-agent-user-and-memory-governance.md`
- `docs/APP-DEVELOPMENT-POLICY.md`
- `docs/PROJECT-POLICY.md`