Risks and Technical Debts

This chapter documents known risks and technical debts.

Known Risks

This list is taken from the PRD’s risk assessment.

Table 1. Risk Assessment

Risk Level

Description

Mitigation Strategy

High

Include Resolution Complexity: Circular includes or complex, deeply nested dependency chains could lead to infinite loops or poor performance during parsing.

The custom parser must include robust cycle detection and set a reasonable limit for include depth.

High

File Corruption: Concurrent modifications or application crashes could corrupt files.

This is directly mitigated by the atomic write strategy (ADR-004).

High

Performance: The in-memory index for very large projects (>600 pages) could consume excessive memory or slow down startup.

This is mitigated by the current design for the specified scale. If projects grow larger, a move to a persistent index (alternative in ADR-002) might be necessary.

Medium

Format Variations: Different dialects of AsciiDoc/Markdown could be parsed incorrectly.

The custom parser will focus on a well-defined, common subset of the languages. Comprehensive testing with real-world documents is required.

Technical Debts

Technical debt consists of design or implementation choices that are expedient in the short term but may lead to future costs.

Table 2. Technical Debt

Item

Description

Consequence / Repayment Strategy

Custom Parser (ADR-005)

Building a custom parser is a significant undertaking and creates a complex component that must be maintained.

Consequence: High maintenance cost. Repayment: As AsciiDoc parsing libraries in Python mature, periodically re-evaluate whether this component can be replaced with a standard, community-maintained library.

No File Watching

The in-memory index (ADR-002) does not automatically update if files are changed externally (e.g., by a user in a text editor).

Consequence: The index can become stale, leading to incorrect data being served. Repayment: Implement a file-watching mechanism that triggers a re-indexing of changed files. This was deferred to reduce initial complexity.

Technical Debt Tracking

Implementation-related technical debt is tracked as GitHub issues with the tech-debt prefix. These issues document gaps between specification and implementation that are deferred for future work.

Table 3. Active Tech-Debt Issues
Issue Description

TD-ADOC-001

AsciiDoc ifdef/ifndef conditional support

TD-ADOC-002

Include options and attribute substitution in paths

tech-debt: Markdown Parser

Additional features from spec (end_line, reserved frontmatter fields, content extraction)

tech-debt: Structure Index

File→Sections mapping, rebuild() method, element index within section
Note
 For the current list of all tech-debt issues, see the GitHub Issues with tech-debt label.