| name | rag-index-decisions |
| description | After making a non-obvious architectural decision, solving a novel bug, agreeing on a coding standard, or reaching a conclusion worth remembering, index it back into the knowledge base so the next occurrence is one search away. Uses add_document or add_from_url. Closes the feedback loop that makes a RAG-backed team compound over time. |
| metadata | {"type":"rag-workflow","kind":"maintenance","target":"any-mcp-client"} |
rag-index-decisions — close the feedback loop
When to use this skill
Trigger this skill when, during a session, the team (or the agent + user together) produces:
- A design decision with tradeoffs discussed (worth an ADR)
- A novel bug fix whose root cause is non-obvious
- A convention agreed on ("from now on we do X for Y")
- A postmortem summary — even a paragraph
- A URL / doc / paper that shaped the decision (worth ingesting via
add_from_url)
Do NOT trigger for:
- Trivial fixes (typo, formatting, obvious one-liner)
- Session-only context that will not matter next time
- Highly sensitive material that should NOT be in the RAG (secrets, PII, WIP negotiations)
- Duplicates of things already indexed
What this skill commits to
When the session produces something worth remembering, the agent proactively suggests indexing it — either:
- As a new file written to
documents/ and indexed via add_document, OR
- As a URL ingestion via
add_from_url if the reference lives elsewhere
The agent does NOT silently index things — always asks the user first, offering a preview of the content and where it will go.
Steps
-
Recognize the moment. The session hit one of the triggers above.
-
Draft the artifact in your head. Typical shapes:
- ADR (Architecture Decision Record): ~200-500 words, structured as Context / Decision / Consequences.
- Runbook update: step-by-step reproducible playbook.
- Postmortem: what happened / root cause / fix / prevention.
- Coding standard: "for X, do Y (not Z), because W."
-
Propose to the user:
"This decision looks worth remembering. I can:
(a) Create docs/adr/0045-token-storage.md with a 300-word ADR summarizing what we agreed, then index it.
(b) Just record the summary here, no indexing.
Which?"
-
If the user picks indexing, write the file to an appropriate path under documents/ (or wherever the config's documents_dir points), then:
add_document(filepath="documents/adr/0045-token-storage.md",
category="adrs")
-
For external references (a URL that shaped the decision):
add_from_url(url="https://datatracker.ietf.org/doc/html/rfc9110",
category="external-refs")
The add_from_url tool fetches, sanitizes, wraps in a provenance fence
(defends against prompt injection per OWASP LLM01:2025), then indexes.
-
Confirm success by immediately searching for it:
search_knowledge(query="<decision keywords>", max_results=3)
Verify the new content shows up. If not, reindex_documents(force=false)
forces a smart reindex.
-
Cross-link in the new document — reference related ADRs, runbooks,
incident reports. This builds the semantic graph that makes
search_similar powerful later.
Examples
Example 1 — New ADR from a design discussion
User: "OK, we decided: rotate refresh tokens on every use, 30-day max lifetime, revoke all tokens on password change."
Agent:
"That is a clean architectural decision worth an ADR. I can draft:
docs/adr/0045-refresh-token-rotation.md
---
# ADR-0045: Refresh Token Rotation on Every Use
## Context
Refresh tokens were fixed-lifetime, revealed once per session. Attacker
who intercepts a token gets 30 days of access.
## Decision
- Rotate refresh token on every use (issue new, invalidate old)
- Max lifetime: 30 days
- Password change revokes all tokens for the account
## Consequences
+ Compromised token has ≤ 1 request lifespan
+ Detection: reuse of a rotated token = clear signal of theft
- Complexity: need atomic rotate+revoke, race conditions
- Storage: revoked-token set grows (mitigate with TTL)
## Related
- ADR-0018 (base auth design)
- RFC 6819 §5.2.2.3 (token rotation guidance)
---
Then: add_document(filepath='docs/adr/0045-refresh-token-rotation.md', category='adrs')
OK to proceed?"
User: "Yes, do it."
Agent:
[Writes file, calls add_document, then confirms with a search]
search_knowledge(query='refresh token rotation') → new ADR appears at score 0.92
"Done. ADR-0045 is indexed and searchable. Next time anyone asks about refresh
tokens, rag-check-first will surface it immediately."
Example 2 — Postmortem from a bug fix
User: "OK that was painful. FTS5 index went silent after nuclear rebuild because the marker file had stale 'complete' but the actual FTS5 table was empty."
Agent:
"Worth a short postmortem so this bites nobody again. Draft:
documents/incidents/2026-08-15-fts5-silent-after-rebuild.md
---
# Incident: FTS5 Fast-Path Silent After Nuclear Rebuild
Date: 2026-08-15
Component: mcp_server/fts5_index.py + server.py
Severity: silent — no error surfaced, queries returned empty
## What happened
...
## Root cause
...
## Fix
...
## Detection for next time
Search for 'FTS5 silent' or 'fast-path empty' in RAG.
---
add_document then search to verify. Proceed?"
Example 3 — External URL worth ingesting
User: "This paper on multi-vector retrieval changed my mind on our reranker choice."
Agent:
"I can ingest it directly:
add_from_url(url='https://arxiv.org/abs/2402.15059', category='research')
The URL ingest will:
1. Fetch the HTML / PDF
2. Strip navigation, keep content
3. Wrap in a provenance fence (marks external, defends against prompt injection)
4. Index like any other doc
Proceed?"
Edge cases
- User is not sure what category — check
list_categories() output and suggest the closest one, or offer to create a new category.
- Secret material — if the user pastes credentials, tokens, or PII, do NOT index it. Say: "I noticed this contains what looks like a credential — indexing would put it in the corpus permanently. Redact before indexing?"
- Duplicate detection — before writing,
search_knowledge(query='<title of the new doc>') to check if something very similar already exists. If yes, offer to update_document instead of adding a new one.
- Very sensitive project — some orgs forbid AI writing to the corpus. Respect the setting; offer just to draft the file for the human to commit.
Related skills
rag-troubleshoot — the natural upstream: after a novel bug fix, index the postmortem.rag-code-review — the other upstream: after a review surfaces a new pattern, index it.rag-onboard-context — the next session's onboarding will surface the new index; this closes the loop.rag-evaluate-quality — after significant indexing activity, worth measuring quality delta.
