explore: incomplete section detection (Raises exists but missing exceptions)

[Alberto-Codes]

Summary

Explore detecting incomplete docstring sections — e.g., a Raises section that exists but doesn't list all raised exceptions, or an Args section missing some parameters.

Current behavior

Docvet's enrichment check detects missing sections (no Raises section at all). It does not detect incomplete sections (Raises section exists but omits some exceptions).

Proposed behavior

def transfer(source: Account, target: Account, amount: Decimal) -> Receipt:
    """Transfer funds.

    Raises:
        ValueError: If amount is negative.
    """
    if amount <= 0:
        raise ValueError("Amount must be positive")
    if source.balance < amount:
        raise InsufficientFundsError(source, amount)  # NOT in Raises section

Current: no finding (Raises section exists).
Proposed: finding for InsufficientFundsError not documented.

Complexity considerations

This is significantly harder than missing-section detection because:

1. Must parse section content, not just section headers
2. Must match raised exception names against documented names (string matching with aliases)
3. Must handle re-raises, conditional raises, and exception chaining
4. Args completeness requires matching parameter names against documented names
5. False positive risk is higher (runtime-constructed exceptions, raise in try/except)

Prior art

pydoclint does this — it checks whether docstring Args/Returns/Raises match the function signature and implementation. This would put docvet in direct feature parity on completeness detection.

Recommendation

Start with an exploration spike to assess false positive rates on real codebases before committing to a full implementation. Consider:

• Args completeness first (simplest — parameter names are in the AST)
• Raises completeness second (harder — exception names require scope analysis)
• Returns completeness third (hardest — return type inference)

Context

Listed as a PRD Growth item. Surfaced during BMAD planning audit (2026-03-06). Marked as exploration — not a commitment until spike validates feasibility and false positive rates.