Context
arc42 chapter main files currently contain manually maintained link tables and direct include::[] statements for each detail document. This creates repeated maintenance work: adding a new ADR, risk, quality scenario, or chapter detail page also requires updating the chapter main document manually.
The preferred pattern is to let AsciiDoc's native TOC handle navigation and to let the generator create chapter-level include fragments. Chapter main documents should keep stable metadata, anchors, and chapter summaries, but should no longer maintain hand-written table-of-contents tables or manually list all detail includes.
Goals
- Replace hand-written chapter link tables with native AsciiDoc TOC behavior.
- Generate chapter include fragments for arc42 chapters.
- Sort generated chapter includes by artifact ID.
- Include generated index fragments directly instead of through non-generated wrapper documents such as
adr-index.adoc.
- Apply the pattern consistently across arc42 chapters.
- Update contracts, README, and skills so future work follows the new pattern.
Decisions
- Generated chapter include order is based on artifact ID, even when this changes the current hand-written order.
- Wrapper documents that only include generated indexes should be removed or replaced by direct generated includes.
- Generated files remain derived output and are not committed as source truth.
Proposed slices
- Update contracts, README, and skills to describe the new chapter assembly pattern.
- Extend the generator to create deterministic chapter include fragments sorted by artifact ID.
- Migrate arc42 chapter main files to native TOC plus generated chapter include fragments.
- Remove generated-index wrapper documents and related metadata/relations once the direct include pattern is in place.
Acceptance criteria
- The project contract no longer requires hand-written chapter link tables.
- The generator can produce include fragments for each chapter.
- Chapter main files no longer need manual detail includes when new artifacts are added.
- Wrapper documents that only include generated index fragments are removed where direct generated includes are sufficient.
- Tests cover deterministic include fragment generation and ordering by artifact ID.
- Rendered arc42 output remains valid.
Context
arc42 chapter main files currently contain manually maintained link tables and direct
include::[]statements for each detail document. This creates repeated maintenance work: adding a new ADR, risk, quality scenario, or chapter detail page also requires updating the chapter main document manually.The preferred pattern is to let AsciiDoc's native TOC handle navigation and to let the generator create chapter-level include fragments. Chapter main documents should keep stable metadata, anchors, and chapter summaries, but should no longer maintain hand-written table-of-contents tables or manually list all detail includes.
Goals
adr-index.adoc.Decisions
Proposed slices
Acceptance criteria