motief/thoughts/shared/designs/2026-03-24-mindmodel-generation-design.md

date	topic	status
2026-03-24	mindmodel-generation	draft

Problem Statement

We generated a .mindmodel/ snapshot for this repository using an automated orchestrator. The output includes inferred constraints, patterns, schema snippets, and remediation recommendations. We need a short, validated design that explains what was produced, how to verify and integrate it safely, and a recommended next set of changes (low-risk remediation and CI additions).

Constraints

Non-negotiables:

• Keep the generated .mindmodel/ files read-only until validated.
• Do not make behavioral changes to production code in the same change as model metadata updates.
• Avoid committing secrets or lockfiles without explicit review.

Limitations:

• The orchestrator used heuristic file reads; some evidence pointers may be truncated or approximate.
• No poetry.lock / requirements.txt or CI workflows were found; dependency remediation must be conservative.

Approach

I'm choosing an audit-first, incremental integration approach because the generated artifacts are high-value policy documents but rely on evidence that needs verification. We will: (1) validate evidence pointers and missing files, (2) mark fixes for trivial issues (move pytest to dev-deps, add formatter configs) in a small non-invasive PR, (3) integrate the .mindmodel/ into the repo and add a CI lint step that validates the manifest, and (4) iterate on higher-risk changes after tests pass.

Alternatives considered:

• Accept-and-commit everything immediately (faster) — rejected because of truncated reads and potential wrong pointers.
• Manual rewrite of constraints by hand (accurate) — rejected due to time cost; validation + targeted fixes gives best ROI.

Architecture

This is a documentation/metadata integration task, not a runtime service. Components:

• .mindmodel/: constraint files and manifest produced by orchestrator. Source of truth for conventions and inferred patterns.
• Validator job (CI): lightweight script/CI step that verifies manifest consistency, required files exist, and key evidence pointers resolve.
• Small remediation PRs: conservative code/config edits (pyproject tweaks, add black/ruff/isort configs, pre-commit) that enable future automation.

Components

• Constraint Validator: verifies every .mindmodel/ constraint references existing files; flags truncated evidence ranges; ensures no secrets.
• Staging branch: holds small remediation commits; each commit is limited to one class of change (deps dev/prod move, linters, CI yaml).
• CI pipeline changes: add a validation job and a docs check that ensures .mindmodel/ manifest is up to date.

Data Flow

1. Orchestrator output (.mindmodel/) exists in the working tree.
2. Validator runs locally or in CI to check pointers and file existence.
3. Developer reviews validator report and accepts/edits constraint files.
4. Remediation PRs are opened for low-risk fixes.
5. CI runs tests + validator; on green we merge and enable scheduled checks.

Error Handling

• Validator failures are non-blocking for mainline but must be resolved before we rely on constraints for automation.
• If a constraint references a deleted or moved file, mark the constraint as "needs-review" in the manifest and leave file unchanged.
• For ambiguous evidence (truncated reads), add an explicit comment in the constraint file pointing to the reviewer.

Testing Strategy

• Unit: small pytest tests that assert README/pyproject presence and that manifest YAML parses.
• Integration: CI job that runs the Constraint Validator and fails on missing files or secrets.
• Manual: reviewer inspects a sample of constraint files (3-5) for accuracy before merging.

Open Questions

• Do we want the validator to auto-fix trivial issues (reformatting YAML paths) or only report? I'm leaning toward report-only for safety.
• Should .mindmodel/ be protected by branch policy or just reviewed by humans? Recommend human review + CI check, not protected branch yet.

Next Steps (what I'll do now)

1. Create this design doc (done).
2. Commit the design doc to the repo (doing now).
3. Spawn the planner to create a step-by-step implementation plan based on this design (spawning now).