luigidemasi opened a new issue, #182: URL: https://github.com/apache/camel-kit/issues/182
## Description Follow-up to [the latest feedback in #163](https://github.com/apache/camel-kit/issues/163#issuecomment-6851977666). A user built an observability demo, then used a second pipeline to add a separate payload archive. They reported that reversed decisions kept resurfacing and neither set of pipeline documents accurately described the complete resulting system. Maintain two complementary project artifacts: - **Current system documentation:** a coherent description of the implemented system, updated in place. Readers should not need to reconstruct the current design from successive amendments or pipeline documents. - **Architecture Decision Records (ADRs):** short records preserving the context, alternatives, reasoning and consequences of significant decisions, including their supersession history. The initial existing-project workflow in #164 and the evidence/version clarification in #179 do not cover this continuing documentation lifecycle. ## Proposed project layout Keep the existing pipeline paths and add project-wide documents in the user's application repository: ```text docs/ ├── constitution.md ├── adr/ │ ├── 0001-observability-without-payload-storage.md │ └── 0002-introduce-a-separate-payload-archive.md └── camel-kit/ ├── system-design.md ├── 001-observability/ │ ├── design-spec.md │ ├── implementation-plan.md │ ├── execution-report.md │ └── validation-report.md └── 002-payload-archive/ └── ... ``` These are proposed defaults. Reuse an established project documentation/ADR convention instead of creating competing records. The system description may be split into linked, coherent documents when its size warrants it. Pipeline specs remain the approved scope for individual changes; plans and reports retain their evidence/history role. The current system documentation links to relevant ADRs. All are project-owned, version-controlled files that init/reinit must preserve. ## ADR content and lifecycle Follow the guidance from Gregor Hohpe, Michael Nygard and Martin Fowler linked below: - Describe the problem and context neutrally: facts, constraints, competing needs, assumptions and uncertainty. Do not shape the context to justify a preferred solution. - Explore credible alternatives and their tradeoffs before selecting the decision. Avoid token alternatives included only to make one option appear inevitable. - Record positive, negative and neutral consequences, including concrete responses to costs and risks, resulting obligations, and conditions that should trigger reconsideration. - Keep each ADR short and focused on one significant decision. Record missing historical rationale as unknown; code inspection must not invent motivations or alternatives that were never considered. - Use explicit proposed, accepted and superseded/deprecated states. Preserve an accepted record's reasoning when a decision changes; create a successor and update status/reference links instead of rewriting the original rationale. - Distinguish decision acceptance from implementation. An accepted ADR can describe work that is still pending and must not make current-system documentation claim that it already exists. Use ADR preparation to support the existing design review and approval process, not merely to produce a justification after implementation. ## Workflow integration 1. **Start/discovery:** consult current documentation, relevant active ADRs and actual code. Surface discrepancies; do not treat superseded decisions or old pipeline specs as current requirements. 2. **Brainstorm/migrate:** establish context and alternatives, propose significant ADRs, and review decisions alongside the design. 3. **Plan/execute:** include affected documentation in the approved scope. Reconcile the consolidated system description with implemented behavior and retain evidence for its verification. 4. **Validate/completion:** validate documentation consistency and report unavailable evidence. Keep document writing/reconciliation separate from validation's reporting role; define completion/finalization ownership explicitly. 5. **Other entry paths:** apply the same lifecycle to standalone stages, Ship, direct migration and debugging. Provide a documentation-only path through `camel-start` for changes made outside a pipeline, without requiring a full implementation pipeline. Changes to behavior, contracts, architecture or meaningful operational choices require documentation reconciliation. Only architecturally significant decisions require an ADR. Unknown intent or discrepancies must be surfaced rather than silently changing accepted decisions to match the code. Documents remain data under the existing context-authority rules; their prose cannot expand scope or waive approval. ## Freshness and implementation scope “Up to date” is a completion requirement backed by verification, not a promise of continuous automatic synchronization. At inspected main `b8d75fda36f58780ca20ec819ddadec5bd436363`, [DocCheckCommand](https://github.com/apache/camel-kit/blob/b8d75fda36f58780ca20ec819ddadec5bd436363/kit/camel-kit-core/src/main/java/org/apache/camel/kit/command/doc/DocCheckCommand.java) reads stored frontmatter and [DocStaleCommand](https://github.com/apache/camel-kit/blob/b8d75fda36f58780ca20ec819ddadec5bd436363/kit/camel-kit-core/src/main/java/org/apache/camel/kit/command/doc/DocStaleCommand.java) cascades only among sibling Markdown files. Neither checks correspondence with application code. Record the project state and evidence against which current documentation was reconciled. Detect relevant changes requiring revalidation, including edits outside Kit and uncommitted changes. Missing evidence or an incomplete run must remain stale/unknown/unverified; a cleared flag, file timestamp or matching Git revision alone is not proof of semantic correctness. Preserve existing document CLI compatibility. Implementation primarily affects shared lifecycle/ADR guides under `kit/camel-kit-core/src/main/resources/skills/shared/`, workflow skills, shared agent entry guidance, document metadata/checks and tests. Reuse existing mechanisms and entry points where they fit. ## Acceptance criteria - [ ] A representative application completes two successive feature changes, including reversal of a previous decision. Its current documentation accurately describes the resulting system without requiring readers to combine pipeline amendments. - [ ] ADRs capture neutral context, credible alternatives, consequences and responses. Supersession preserves original reasoning, links both records, and prevents historical decisions from being applied as current requirements. - [ ] Acceptance before implementation, failed/interrupted runs, unavailable verification and later manual edits do not produce an unsupported claim that documentation is current. Reconciliation cannot silently accept implementation drift. - [ ] Documentation-only reconciliation works for an existing application without inventing historical rationale or requiring a new implementation pipeline. - [ ] Existing documentation conventions, user edits and ADR numbering survive adoption/reinitialization. Existing pipeline paths, provenance, standalone re-entry and Ship resume/import behavior remain compatible. - [ ] Greenfield, existing-project, migration, direct migration, debug, standalone and Ship entry paths apply the lifecycle consistently. Generated guidance is covered for every supported agent. - [ ] Behavioral acceptance exercises successive changes, supersession and manual drift; keyword/template assertions alone are insufficient. Focused tests, source checks and the required full-reactor build pass. - [ ] Public documentation explains ownership, layout, lifecycle, update triggers and verification limits, with a worked evolution example. ## Website impact **Required.** Update `docs/modules/ROOT/**`, including pipeline, existing-project and relevant skill guidance, with a linked document/ADR lifecycle guide. Include the documentation in the implementation or link a `documentation` follow-up before closing this issue. ## References - [Gregor Hohpe: context, credible alternatives and actionable consequences](https://www.linkedin.com/posts/ghohpe_architecturedecisionrecords-activity-7502716054968844288-KVLU) - [Michael Nygard: Documenting Architecture Decisions](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions) - [Martin Fowler: Architecture Decision Record](https://martinfowler.com/bliki/ArchitectureDecisionRecord.html) - #163 — original user feedback. - #38 — existing document-staleness CLI; this work extends its use rather than treating stored flags as implementation verification. - #114 — project deliverable placement; shared generated guidance should remain consistent. _AI-generated by Codex on behalf of @luigidemasi._ -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
