This directory contains current reality documentation - what IS, not what we plan or aspire to build.
Evidence documents serve as:
- Ground truth: Accurate reflection of current implementation
- Status tracking: What's done, what's partial, what's missing
- Reality check: Prevent docs from drifting into aspiration
- Progress measurement: Track implementation against plans
Evidence documents describe REALITY, not ASPIRATION.
If it says something exists here, it must actually be implemented and working in the codebase.
- Current implementation status
- Working features with file/line references
- Test coverage metrics
- Performance benchmarks (actual numbers)
- Known limitations
- Tech debt and gaps
- Future plans (→
docs/plan/) - Architectural decisions (→
docs/adr/) - Design proposals (→
docs/design/) - Historical context (→
docs/archive/) - Aspirational claims
| Document | Purpose | Update Frequency |
|---|---|---|
| unvarnished-review.md | Brutally honest project assessment | After major milestones |
| compile-time-contract-implementation.md | Contract system status | With each contract feature |
| implementation-summary.md | Overall implementation status | Weekly |
| scala3-alignment.md | Scala 3 readiness status | As ecosystem evolves |
Plan → Implement → Test → Evidence → Archive (when superseded)
- Plan created: Future work documented in
docs/plan/ - Implementation: Code written, tests pass
- Evidence updated: Document current reality
- Plan archived: Move completed plan to archive
- Evidence maintained: Keep updated as implementation evolves
# [Feature Name] - Implementation Evidence
**Status**: ✅ Complete | 🏗️ Partial | ❌ Not Started
**Last Updated**: YYYY-MM-DD
**Coverage**: X%
## What Works
- Feature A: Implemented in `path/to/file.scala:123`
- Feature B: Tests in `path/to/test.scala:45`
## What's Partial
- Feature C: Core logic done, missing edge cases
- Feature D: Works for Spark, Flink support pending
## What's Missing
- Feature E: Planned but not started
- Feature F: Blocked by dependency X
## Test Coverage
- Unit tests: X% (target: Y%)
- Integration tests: X scenarios
- Compile-fail tests: X proofs
## Known Issues
- Issue #123: Description
- Tech debt: Description
## References
- ADR: [ADR-XXX](../adr/XXX-name.md)
- Plan: [Plan](../plan/feature-plan.md)
- Code: `modules/core/src/...`- Be specific: Include file paths and line numbers
- Quantify: Use metrics (%, counts, times)
- Be honest: Document gaps and limitations
- Link code: Reference actual implementation
- Update regularly: Evidence should never be stale
Before publishing evidence:
- Code exists: Verify all referenced code is in repo
- Tests pass: Run tests for claimed features
- Metrics accurate: Recompute coverage/performance numbers
- Links work: Check all file paths and URLs
- Status current: Ensure status badges reflect reality
Watch for these signs of aspirational creep:
⚠️ "Will be" or "Plans to" language (→ move to plans/)⚠️ Features referenced without file paths⚠️ Claims without test evidence⚠️ Metrics without timestamps⚠️ "Mostly" or "Nearly" complete (be specific!)
| Document Type | Purpose | When | Updates |
|---|---|---|---|
| Evidence | What IS | After implementation | As code changes |
| Plans | What WILL BE | Before implementation | Until completed |
| ADRs | Why we decided | During decision | Immutable (supersede if needed) |
- Plans - What we're building next
- ADRs - Why we made decisions
- Canonical Sources - Topic authority map
- Archive - Historical evidence
When updating evidence:
- Run tests first: Verify claims before documenting
- Use git blame: Find actual implementation dates
- Link issues: Reference GitHub issues for gaps
- Update indexes: Keep CANONICAL_SOURCES.md current
- Be brutally honest: Truth serves the project better than optimism
Remember: Evidence documents are our reality check. Keep them accurate, current, and honest.