---
date: 2026-03-24
topic: "mindmodel-generation"
status: 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).