jpmschweitzer/odysseus
1
0
Fork 0
mirror of https://github.com/pewdiepie-archdaemon/odysseus.git synced 2026-10-10 17:02:20 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs(discovery): improve map readability

Browse Source
This commit is contained in:
Alexandre Teixeira
2026-07-26 14:32:20 +01:00
parent 749b8a949a
commit dfb62c4fba
3 changed files with 157 additions and 125 deletions
Download Patch File Download Diff File Expand all files Collapse all files
specs/discovery/README.md
+23 -20
View File
@@ -1,30 +1,33 @@
# Discovery guide
# Odysseus discovery maps
Discovery keeps a shared maintainer understanding of how the checked-in Odysseus code works without becoming a permanent audit system. It is a compact companion to the code for cross-cutting systems, not a feature certification or a substitute for normal testing.
Compact, code-grounded maps of the cross-cutting systems in the checked-in Odysseus codebase. They are not a feature certification or substitute for normal testing, and do not become a permanent audit system.
## Working model
> [!IMPORTANT]
> Code is the source of truth for current behaviour. These specifications describe only the checked-in system and its current boundaries; keep them synchronized with relevant code changes.
- Code is the ground truth for current behaviour. Trace current paths in source before recording a claim.
- These specs record current code-grounded behaviour and system boundaries only. They do not record accepted intent, design direction, refactor plans, or decision history.
- Keep this package in sync with code changes that alter a documented cross-cutting system, its authority boundary, or its canonical implementation location.
- Do not exhaustively revalidate existing functionality simply because it appears in a map. Investigate when there is a report, normal use visibly fails, a change affects the area, or a high-authority boundary needs review.
- Record a confirmed, actionable problem in the relevant project within the canonical Plane workspace. Keep high-level design, prioritization, ownership, and refactor discussion in Plane. Do not create parallel issue lists here.
- After implementation changes the code, update the relevant map to describe the resulting current state.
- Review safety-sensitive authority first: execution, data access, external tools, credentials, destructive operations, and unattended work.
- Cite stable source locations such as modules, routes, classes, and functions. Avoid fragile line ranges and generated evidence tables.
## Explore the maps
## Package
| Document | Purpose |
|---|---|
| [Current system map](system-map.md) | Explains the current subsystem boundaries, implementation locations, confirmed problems, and factual open questions. |
| [Safety boundaries](safety-boundaries.md) | Maps broad authority, safeguards, confirmed risks or gaps, and unverified behaviour. |
- [Current system map](system-map.md) describes the code-grounded subsystem boundaries.
- [Safety boundaries](safety-boundaries.md) records where review effort is most valuable.
## Working rules
The existing [architecture runtime inventory](../architecture-runtime-inventory.md) remains useful structural context. It is explicitly a draft snapshot; re-check its measurements against the code before using them for an implementation decision.
- **Trace the code first.** Confirm the current path in source before recording a claim.
- **Keep specs current-state only.** Do not record intentions, design direction, refactor plans, or decision history here.
- **Synchronize with code.** Update this package when a code change alters a documented cross-cutting system, authority boundary, or canonical implementation location.
- **Investigate with cause.** Do not exhaustively revalidate existing functionality without a report, visible failure, relevant change, or high-authority review need.
- **Keep planning in Plane.** Record confirmed problems in the relevant project within the canonical Plane workspace; keep high-level design, prioritization, ownership, and refactor discussion there.
- **Review authority carefully.** Give execution, data access, external tools, credentials, destructive operations, and unattended work focused review.
- **Use stable locations.** Cite modules, routes, classes, and functions instead of fragile line ranges or generated evidence tables.
## How to use this package
## Working flow
1. Start at the subsystem in the system map and confirm the relevant source.
1. Start with the relevant map and trace the cited code.
2. For a defect, create or update the relevant project within the canonical Plane workspace with a reproducible report and ownership.
3. For a design, prioritization, ownership, or refactor question, use a Plane thread.
4. Make and validate the implementation through the normal engineering workflow, then update this package if the code changed a documented system boundary.
3. Use a Plane thread for design, prioritization, ownership, or refactor discussion.
4. After implementation changes the code, update the affected map to describe the resulting current state.
This package intentionally has no generator, validator, maturity scale, feature database, or duplicate work tracker.
> [!NOTE]
> This package intentionally contains no generator, validator, maturity scale, feature database, or parallel work tracker. The [architecture runtime inventory](../architecture-runtime-inventory.md) remains useful structural context, but is an explicitly draft snapshot.