refactor/metadata-generation #72
Description
Title
Refactor user-facing metadata generation/management docs and align tooling strategy across Forge and g3t repositories.
Summary
Metadata generation and metadata management are currently difficult for users and contributors to understand and execute consistently. Existing efforts appear fragmented across multiple repositories, resulting in duplicated work, inconsistent guidance, and avoidable rework.
This issue proposes a coordinated refactor that improves:
- User-facing documentation coherence
- User-facing tooling coherence
- Developer tooling efficiency and ownership
Problem Statement
Current work on metadata generation and metadata management appears to be suffering from a lack of sustained attention and expert ownership, especially around g3t-based workflows. At the same time, there is no coherent replacement strategy, which increases risk of churn and wasted effort.
The impact is evident across:
- Incomplete or inconsistent user guidance for metadata lifecycle tasks
- Multiple partially overlapping tooling paths for similar workflows
- Developer effort scattered across repositories without clear boundaries
Why This Matters
- New and existing users lack a single, reliable path for metadata generation and management.
- Support burden increases because documentation and tooling behavior diverge.
- Developer time is wasted on one-off fixes, duplicate implementation work, and migration dead-ends.
- Program risk increases when key workflow knowledge is concentrated in too few contributors.
Repositories involved
Scope
1) Lack of coherent user documentation
- Audit all metadata generation/management documentation references in CALYPR docs and linked repos.
- Define one canonical user journey for metadata generation and one for metadata management.
- Mark legacy paths as deprecated where appropriate.
- Publish a single navigation entry point for users with explicit "recommended path" guidance.
2) Lack of coherent user tools
- Inventory current user-accessible tools/commands and identify overlaps.
- Decide and document one preferred user toolchain for each common scenario.
- Standardize terminology and input/output expectations across tools.
- Provide migration guidance when moving users away from legacy g3t-dependent flows.
3) Inefficiencies and rework in developer tools
- Clarify repository ownership and responsibilities for:
- Forge
- g3t_etl
- g3t
- Identify duplicated implementation efforts and integration debt.
- Define minimum interoperability contracts (schemas, interfaces, expected artifacts).
- Establish a replacement or stabilization strategy for g3t-based components with named owners and milestones.
Concerns to explicitly track
- Potential wasted effort in continuing ad hoc g3t-based metadata generation/management work without clear ownership.
- Knowledge concentration and expertise gaps that create maintenance risk.
- Ongoing rework caused by parallel but uncoordinated implementations.
- Risk of stalled progress because no coherent replacement strategy currently exists.
Proposed Deliverables
- Architecture and ownership decision record for metadata generation/management.
- Consolidated user documentation plan and publication schedule.
- Tooling matrix mapping use-cases to preferred tools.
- Deprecation/migration plan for redundant or unsupported flows.
- Milestone plan with accountable owners across affected repositories.
Acceptance Criteria
- A single, clearly documented recommended path exists for users to generate and manage metadata.
- Deprecated/legacy paths are explicitly labeled and include migration guidance.
- Cross-repo responsibilities are documented and approved by maintainers.
- A coherent strategy exists for either (a) stabilizing g3t-based workflows or (b) replacing them, with deadlines and owners.
- New contributor onboarding can identify where to implement metadata features without ambiguity.
Milestones
- Discovery & audit
- Decision & design
- Migration implementation
- Documentation release