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]

Reply via email to