17 lines
1.5 KiB
Markdown
17 lines
1.5 KiB
Markdown
# Research Findings: AI-Facing Repository Constitution
|
||
|
||
## Decision 1: Constitution is authoritative for AI
|
||
- **Decision**: AI-facing constitution overrides conflicting human docs for AI guidance; conflicts trigger updates to both with recorded resolution.
|
||
- **Rationale**: Ensures consistent automated actions and avoids drift between AI behavior and repo rules.
|
||
- **Alternatives considered**: (a) Defer to human docs and mirror later (rejected: increases drift); (b) Split authority by domain (rejected: adds ambiguity for AI tools).
|
||
|
||
## Decision 2: Documentation IA
|
||
- **Decision**: Place the living constitution in `/docs`; keep feature-specific planning/playbooks under `specs/001-ai-docs/` with index links in constitution.
|
||
- **Rationale**: Clear separation of durable source-of-truth vs feature-level artifacts; aligns with spec expectations.
|
||
- **Alternatives considered**: (a) Keep all AI docs in `/specs` (rejected: mixes planning with durable guidance); (b) Distribute docs per module directory (rejected: harder AI discoverability).
|
||
|
||
## Decision 3: Validation approach
|
||
- **Decision**: Validate docs manually against repo conventions and the specification’s success criteria (discoverability ≤2 steps, full module/host coverage, secrets map completeness).
|
||
- **Rationale**: No automated tests for markdown; checklist-based review matches spec.
|
||
- **Alternatives considered**: (a) Add automated linting now (rejected: out-of-scope for this documentation feature); (b) No validation (rejected: risks drift and omissions).
|