| 1 | # Information Management Playbook v1 |
| 2 | |
| 3 | ## Purpose |
| 4 | Project-independent domain base for engineering Information Management (IM). |
| 5 | This file stores stable IM concepts, rules, and decision patterns that do not depend on a specific product. |
| 6 | |
| 7 | ## Domain Goal |
| 8 | - Keep engineering information consistent, traceable, and auditable across its lifecycle. |
| 9 | - Reduce semantic ambiguity between source systems, users, and downstream consumers. |
| 10 | |
| 11 | ## Core Domain Objects |
| 12 | - Document |
| 13 | - Revision |
| 14 | - Version |
| 15 | - File |
| 16 | - Tag |
| 17 | - Relationship (Document-Tag, Document-Document, Tag-System, Tag-Tag) |
| 18 | - Attribute and Classification |
| 19 | - Workflow State (Draft, Verified, Approved, Archived, Superseded) |
| 20 | - Provenance (source system, source field, sync event) |
| 21 | |
| 22 | ## Canonical Domain Rules |
| 23 | - Every critical field must be traceable to source provenance. |
| 24 | - Revision and version semantics must be explicit and non-ambiguous. |
| 25 | - Lifecycle transitions must be guarded and auditable. |
| 26 | - Validation must return actionable diagnostics (where, why, impact, fix path). |
| 27 | - Human-readable state must match system state at all times. |
| 28 | - Reference data (classifiers, dictionaries, unit systems) must be versioned. |
| 29 | - Bulk updates must support preview (dry-run) and deterministic rollback. |
| 30 | |
| 31 | ## Architecture Lens (Pipeline/Compiler Model) |
| 32 | - Ingestion adapters -> parse and normalize source payloads. |
| 33 | - Semantic validation -> enforce IM invariants. |
| 34 | - Canonical IR -> source-agnostic information graph. |
| 35 | - Passes -> dedup, conflict resolution, enrichment, indexing. |
| 36 | - Projections -> API contracts, UI workbench views, exports, reports. |
| 37 | |
| 38 | ## Integration and Interop Principles |
| 39 | - Keep canonical contracts stable and explicit at boundaries. |
| 40 | - Separate source-specific mapping from canonical ontology. |
| 41 | - Preserve backward compatibility with versioned contract evolution. |
| 42 | - Treat source connectors as replaceable adapters, not core domain logic. |
| 43 | |
| 44 | ## UX Contracts |
| 45 | - Progressive disclosure with expert acceleration paths. |
| 46 | - Context-preserving navigation across Document/Revision/Version. |
| 47 | - Semantic compare over metadata + links + file preview. |
| 48 | - Conflict center with safe bulk operations and dry-run preview. |
| 49 | - Approval board with immutable approval snapshots. |
| 50 | |
| 51 | ## Evidence Contract |
| 52 | - Treat IM/AVEVA claims as factual only with source docs or code references. |
| 53 | - Separate facts from hypotheses in design notes. |
| 54 | - Record confidence and evidence quality independently. |
| 55 | - Keep a glossary for overloaded terms (document, revision, version, baseline, status). |
| 56 | |
| 57 | ## Open Questions Backlog |
| 58 | - Canonical mapping of AVEVA-like concepts to neutral IM ontology. |
| 59 | - Conflict precedence policy across multiple upstream systems. |
| 60 | - Minimal immutable snapshot schema for approvals. |
| 61 | - IR versioning strategy for long-running migration compatibility. |
| 62 | |
| 63 | ## Project Overlay Contract |
| 64 | - Product-specific decisions (for example IMC UX, repo paths, sprint scopes) stay in canonical notes sections like `scope-imc` and related `imc-*` blocks. |
| 65 | - This playbook remains domain-only and reusable across projects. |
| 66 | |
| 67 | |