epam Finding the authoritative source
A router. Pick the row, open that source, stop. Two questions decide where to look:
- What is this supposed to do? → a capability spec. 116 of them, ~15,500 lines. This is the behavioral source of truth.
- Why is it like this? → the archived change that introduced it.
proposal.mdcarries the problem and the alternatives considered;design.mdcarries the tradeoff that was accepted.
Everything else is a much smaller tail. docs/ is ~380 lines and covers only ops-facing concerns.
Capability specs — what the system does
openspec/specs/<capability>/spec.md, each ## Purpose then ### Requirement: /
#### Scenario: blocks. The scenarios are the acceptance criteria, so a spec answers "is this
behavior intended?" without reading the implementation.
To find the right capability:
openspec list --specs # all capabilities with requirement counts
openspec show <capability> # one spec
grep -rl "<term>" openspec/specs/ # when you don't know the capability name
.claude/reference/areas.md maps routes and component folders to areas, which is usually the
fastest way from a file you're editing to the capability that governs it.
Analytics is a folder of sub-capabilities, not one spec. openspec/specs/analytics/spec.md is a
short index — read its routing table, then open the single sub-capability that answers the question:
analytics/query-builder (authoring a query: Form, JSON, SQL, AI views), analytics/query-viewer
(running one and reading the result), analytics/saved-queries, analytics/tables,
analytics/conversations-listing, analytics/conversation-trace-listing,
analytics/conversation-trace-detail, analytics/pipelines, analytics/evaluators. Don't create a
top-level analytics-* folder.
Change history — why it is that way
| Question | Read |
|---|---|
| What work is in flight right now? | openspec/changes/<name>/ (4 active) |
| Why was this built this way? What else was considered? | openspec/changes/archive/<date>-<name>/proposal.md |
| What tradeoff was accepted, and what was explicitly ruled out? | openspec/changes/archive/<date>-<name>/design.md |
163 archived changes. When a design decision looks arbitrary, it is usually recorded here — check before re-litigating it.
Ops and product docs
| Question | Read |
|---|---|
| What changed for deployment in a version? Was an env var added, renamed, removed? | docs/INFRA-CHANGELOG.md |
| What is required to move to a released version, in priority order? | docs/upgrade-plans/<version>.md |
| What is the navigation menu's structure — groups, titles, icons, route links? | docs/MENU-DOCUMENTATION.md |
What does the Preview tag mean and when is it applied? |
docs/PREVIEW_TAG.md |
| How are colors, fonts, and images customized without rebuilding the image? | docs/THEME-CUSTOMIZATION.md |
Stack, commands, conventions
openspec/config.yaml — tech stack, path alias, commands, provider stack, entity pattern, grid and
i18n conventions. AGENTS.md for how agents work here. Coding rules live in .claude/rules/ and
load themselves for matching files.
Precedence when sources disagree
- The consolidated spec (
openspec/specs/) is current intended behavior. - An archived change is historical rationale — accurate about why, possibly superseded about what. A later change may have replaced it.
docs/upgrade-plans/is generated fromdocs/INFRA-CHANGELOG.md; the changelog wins.- Code wins over all of them for what actually happens today. A spec that disagrees with shipped behavior is a finding worth raising, not a fact to repeat.
Confirm env var names against the code that reads them, not prose — a changelog entry can lag a rename.
Writing back
When a change alters behavior one of these sources describes, update it in the same change:
- Behavior change → the capability's delta spec, folded into
openspec/specs/<capability>/spec.md - New or renamed env var →
docs/INFRA-CHANGELOG.md - Menu change →
docs/MENU-DOCUMENTATION.mdand.claude/reference/areas.md, which mirrors the menu and is what tooling reads