manual_slop/conductor/tracks/sdm_docstrings_20260509/spec.md

Specification: Structural Dependency Mapping (SDM) Docstrings

Overview

Introduce a project-wide convention for "Structural Dependency Mapping" (SDM) in Python docstrings. This convention requires that all state variable declarations, methods, and functions include terse metadata indicating their usage, mutation points, and callers. This ensures that AI agents can accurately assess the impact of refactors beyond immediate scope.

Goals

• Improve AI agent context regarding non-local dependencies in a dynamic language (Python).
• Minimize token burn through a terse, standardized tag format.
• Ensure the convention is self-sustaining by documenting it in the project's core guidelines.

SDM Tag Convention

Docstrings will include specific tags at the bottom:

• For Functions/Methods: [C: Caller1, Caller2] (List of primary calling functions/methods).
• For State Variables: [M: FileA:Line, MethodB] (List of mutation points/files) and [U: FileC] (Major codepaths of use).

Example:

def update_registry(self, data: dict) -> None:
 """
 Updates the central provider registry.
 [C: _cb_load_config, start_services]
 """
 ...

Functional Requirements

• Update Guidelines: Add the SDM convention to conductor/product-guidelines.md and conductor/code_styleguides/python.md.
• Codebase Rollout: Perform a global batch update of ./src, ./simulation, and ./tests to inject SDM tags into existing definitions.
• Verification: Ensure the batch update does not introduce syntax errors or logical regressions.

Implementation Strategy

• Hybrid Automation: Use a Tier 4 QA sub-agent or a specialized static analysis script (leveraging tree-sitter or the project's existing AST tools) to generate the initial mapping.
• Human/Agent Review: A reasoning-heavy agent must review the generated tags before final injection to ensure accuracy.

Acceptance Criteria

• SDM convention is documented in product-guidelines.md and python.md.
• All major state variables, methods, and functions in ./src have SDM tags.
• Full test suite passes after injection.
• AI agents (Tier 2/3) demonstrate awareness of the tags in a sample refactor turn.