rag-domain-integrity-gate

Files (1)

• SKILL.md

SKILL.md (first lines)

# rag-domain-integrity-gate

Goal: prevent corruption of the domain layer in RAG and halt the pipeline immediately upon regression detection.

## When to use

- `domain_path_like > 0` after refresh or build
- sudden increase in `domain` count without real domain changes
- domains look like file paths (`martous\controllers\x.cs`)
- after changes to `workflow-knowledge` or the incremental rebuild engine

## Quick diagnosis

1. Count path-like domains:

- `type=domain` and `title` contains `/` or `\`
- `code_file.domain` and `file_summary.domain` contains `/` or `\`

2. Check data sources:

- `workflow-summary-log.csv` field `domain`
- node creation sites `New-Node -Domain ...`
- normalization in `Get-DomainFromRelativePath`

3. Check selective refresh:

- whether `index-and-summaries` skips hash updates
- whether domain layer rebuild is deterministic

## Root causes (most common)

1. Missing normalization of `summary.domain` (CSV) before writing to node.
2. Incorrect backslash replacement in PowerShell (`Replace('\\','/')` instead of replacing a single `\`).
3. Different `path-like` definitions across scripts.
4. Missing fail-fast gate (only warnings, pipeline continues).

## Fix standard

1. Fix source normalization:

- If `domain` looks like a path (`[/\]`) -> recalculate via `Get-DomainFromRelativePath`.

2. Unify path-like definitions:

- One rule: path-like = contains `/` or `\`.
- Do not treat suffix `.cs/.ts` alone as path-like without a separator.

3. Add fail-fast to the validator:

- `validate-rag-graph.ps1` should return `path_like_domain_count` and optionally throw an exception (`-FailOnPathLikeDomain`).

4. Hook gate into entry points:

- `refresh-rag-summaries-only.ps1`
- `run-rag-maintenance.ps1`
- `workflow-metrics-core.ps1` (finalize)

5. Add Pester tests:

- path-like domain detection
- fail-fast throw with `-FailOnPathLikeDomain`
- Pester 3 syntax compatibility (`Should Throw`)

## Definition Of Done

- `domain_path_like = 0` after `index-and-summaries` refresh
- `validate-rag-graph -FailOnPathLikeDomain` blocks regressions
- Pester tests for gate pass
- no recurrence of path-like domain growth in subsequent iterations

## Output policy

- Run the integrity gate (`validate-rag-graph.ps1`) itself without `OutputMode`.
- When gate is run by finalize, run finalize by default in `OutputMode quiet`.
- On finalize failure: first read `.github/agents/diagnostics/*.json`, then retry finalize in `OutputMode diagnostic`.

## Result

- PASS: no path-like domains and no stale entries
- WARN: stale entries > 0, but path-like domains = 0
- BLOCK: path-like domains > 0 (fix mandatory before continuing)

From ArkadiuszSieracki/mastermind-agentic-sdlc-vscode-copilot, Apache-2.0.

More from ArkadiuszSieracki/mastermind-agentic-sdlc-vscode-copilot