@rkarim08/sia 1.0.0

package/skills/sia-playbooks/reference-tools.md

@@ -0,0 +1,239 @@
+# Sia — Full Tool Parameter Reference
+
+*Read this module when you need complete parameter documentation for any Sia tool,*
+*or when the base module's condensed guidance is insufficient for the task at hand.*
+
+---
+
+## `sia_search` — General Memory Retrieval
+
+Your primary tool. Call at the start of every non-trivial task.
+
+```
+sia_search({
+  query: string,
+  // Conversational language works well: "session timeout expiry behavior"
+  // rather than keyword fragments: "timeout session".
+
+  task_type?: 'bug-fix' | 'feature' | 'review',
+  // Boosts entity types relevant to the task:
+  //   bug-fix  → Bug, Solution, Decision entities ranked higher
+  //   feature  → Concept, Decision entities ranked higher
+  //   review   → Convention entities ranked higher
+
+  node_types?: string[],
+  // Further narrow by type: ['Decision','Convention'], ['Bug','Solution'], etc.
+  // Use when you know the category of what you're looking for.
+
+  package_path?: string,
+  // Monorepo: scope to a specific package path. Reduces cross-package noise
+  // when working in a single package of a large monorepo.
+
+  workspace?: boolean,
+  // Default false. Set true ONLY for cross-repo tasks: API contracts between
+  // linked repositories, shared types, cross-service calls.
+  // Never use for single-repo tasks — adds 400ms latency and cross-repo noise.
+
+  paranoid?: boolean,
+  // Default false. Set true when auditing external dependencies or when you want
+  // to query the graph without surface-level exposure to Tier 4 content.
+  // Filters Tier 4 entities from retrieval results only — does NOT prevent Tier 4
+  // content from being captured into the graph, and does NOT guarantee memory
+  // integrity.
+  //
+  // If the developer expresses concern about memory poisoning or graph integrity,
+  // paranoid: true on queries is insufficient. Direct them to:
+  //   paranoidCapture: true in ~/.sia/config.json
+  // which quarantines Tier 4 at the chunker stage (the hard guarantee). For past
+  // captures, suggest: sia rollback to inspect and revert if needed.
+
+  limit?: number,
+  // Default 5. Use 10 for architectural queries. Use 15 ONLY for PR review
+  // (full convention coverage required). Never use 15 as a default.
+
+  include_provenance?: boolean,
+  // Default false. When true, adds extraction_method to entity results.
+  // WHEN TO USE — set true only when:
+  //   (a) two Tier 3 results contradict each other (spacy is more reliable
+  //       than llm-haiku — provenance lets you choose the more reliable one)
+  //   (b) the developer asks how a fact was captured
+  //   (c) you are about to use a Tier 3 entity as a hard constraint on a
+  //       security-critical or data-migration task
+  // DO NOT use by default — adds payload for no benefit on routine queries.
+  //
+  // Values when true:
+  //   'tree-sitter' = deterministic AST extraction (Tier 2, fully reliable)
+  //   'spacy'       = deterministic NLP (Tier 3, highly reliable)
+  //   'llm-haiku'   = probabilistic LLM extraction (Tier 3, can hallucinate)
+  //   'user-direct' = developer stated this explicitly (Tier 1)
+  //   'manifest'    = declared in .sia-manifest.yaml (Tier 1)
+  // Conflict rule: prefer 'spacy' over 'llm-haiku' for Tier 3 disambiguation.
+})
+```
+
+---
+
+## `sia_by_file` — File-Scoped Memory Retrieval
+
+Call before modifying any file you have not worked on recently. Returns everything
+Sia knows about that file: decisions made about it, bugs found in it, patterns it
+implements, conventions that apply to it. This is a complement to `sia_search`,
+not an alternative — use both.
+
+```
+sia_by_file({
+  file_path: string,   // relative path from project root
+  workspace?: boolean, // default false — include cross-repo edges for this file
+  limit?: number,      // default 10
+})
+```
+
+---
+
+## `sia_expand` — Graph Relationship Traversal
+
+Call when a search result is relevant but you need to understand how it connects to
+the rest of the graph. Use sparingly — the session budget is 2 calls.
+
+```
+sia_expand({
+  entity_id: string,             // the ID from a sia_search or sia_by_file result
+  depth?: 1 | 2 | 3,            // default 1; see depth guide below
+  edge_types?: string[],         // see edge type guide below
+  include_cross_repo?: boolean,  // default false
+})
+```
+
+**Depth guide:**
+`depth=1` — immediate neighbors only. Use for 90% of cases.
+`depth=2` — multi-step causal chains. Use for regression tracing and dependency audits.
+`depth=3` — full dependency impact. The 50-entity neighbor cap will usually bind here;
+use only when a complete impact analysis is explicitly needed.
+
+**Edge type guide:**
+Regression investigation: `edge_types=['supersedes', 'caused_by', 'solves']`
+Dependency analysis:      `edge_types=['calls', 'imports', 'depends_on']`
+Decision history:         `edge_types=['supersedes', 'elaborates', 'contradicts']`
+Bug-to-solution:          `edge_types=['solves', 'caused_by']`
+
+**Hard constraints:**
+Never expand all results from a `sia_search` — context overflow is guaranteed.
+Never call `sia_expand` on Community entities — they already contain synthesised summaries.
+Budget: 2 calls per session maximum.
+
+**Edge truncation:** `SiaExpandResult.edge_count` is the total active edges in the
+neighborhood. `edges[]` is capped at 200. If `edge_count > edges.length`, the traversal
+is incomplete. Narrow with an `edge_types` filter or reduce `depth` and re-call.
+
+---
+
+## `sia_community` — Architectural Summaries
+
+Use for broad structural questions, architectural orientation, and module-level
+understanding. Not for specific entity lookups — use `sia_search` for those.
+
+```
+sia_community({
+  query?: string,          // topic description for community selection
+  entity_id?: string,      // OR: get the community containing this specific entity
+  level?: 0 | 1 | 2,      // default 1; see level guide below
+  package_path?: string,   // monorepo: scope to a specific package
+})
+```
+
+**Level guide:**
+`level=2` — Coarse architectural overview. Use for: new developer orientation,
+system-wide design questions, "how does this system work?" queries.
+`level=1` — Subsystem / module level. Use for: "how does the auth module work?",
+before implementing a feature that spans a module.
+`level=0` — Fine-grained cluster view. Rarely needed by the agent; more useful
+from the CLI. Avoid in agent workflows.
+
+Never use `sia_search("architecture")` as a substitute for `sia_community` — it
+returns raw entity snippets (a list of class names) rather than synthesised summaries.
+
+---
+
+## `sia_at_time` — Temporal Graph Query
+
+Use for historical investigation: regressions, architecture evolution, "what changed
+about X?", "what was true before this broke?"
+
+```
+sia_at_time({
+  as_of: string,            // ISO 8601 OR relative: "7 days ago", "3 months ago", "January"
+  entity_types?: string[],  // narrow by entity type
+  tags?: string[],          // narrow by tag
+  limit?: number,           // default 20, max 50. Applies to BOTH entities[] and
+                            // invalidated_entities[]. Increase for large regressions
+                            // (many entities changed at once).
+})
+```
+
+**Output:** A `SiaTemporalResult` with two entity arrays and an edge array:
+- `invalidated_entities[]` — facts that ENDED on or before `as_of`. The change history.
+  Sorted by `t_valid_until DESC` (most recently ended first — highest priority for
+  regression diagnosis). Each entry's `t_valid_until` is exactly when that fact ended.
+- `entities[]` — facts still valid at `as_of`. Compare against current `sia_search`
+  output to see what has changed since.
+- `edges[]` — edges valid at `as_of`, capped at 50.
+- `edge_count` — total edges valid at `as_of` before the 50-cap truncation. If
+  `edge_count > edges.length`, the edge set is incomplete — narrow with `entity_types`
+  or `tags` to retrieve remaining edge context.
+
+When `invalidated_count > invalidated_entities.length`, entity results are truncated.
+Make additional narrowed calls with `entity_types` or `tags` filters to retrieve
+remaining entries. Do not assume you have the complete picture until
+`invalidated_count == invalidated_entities.length`.
+
+`sia_at_time` has no meaning in isolation. Always compare its output against the current
+graph (a current `sia_search` call) to identify what changed and what superseded each
+invalidated fact.
+
+**When `t_valid_from` is null in a result:** the entity was recorded but Sia could not
+determine when it became true in the world. Say "this was the state at some point before
+[as_of], but the exact start date is unknown."
+
+---
+
+## `sia_flag` — Mid-Session Capture Signal (If Enabled)
+
+Available only when `sia enable-flagging` has been run. See
+`reference-flagging.md` for full guidance.
+
+```
+sia_flag({ reason: string })   // max 100 characters after sanitization
+```
+
+The `reason` is sanitized before storage. Characters stripped: `<`, `>`, `{`, `}`,
+`[`, `]`, `\`, quotes, and control characters. Permitted: colons, backticks,
+underscores, forward slashes, `@`, and all standard punctuation. Natural root-cause
+descriptions pass through correctly.
+
+If the tool returns a disabled error, tell the developer: "This moment seems worth
+capturing. Run `sia enable-flagging` if you want in-session capture — otherwise
+Sia will attempt to capture it at session end via the Stop hook, with lower precision."
+
+---
+
+## Three Paranoid Modes — They Are Not Equivalent
+
+These are three distinct mechanisms that are frequently confused:
+
+**`paranoid: true` on `sia_search`** (or `sia search --paranoid` from CLI): filters
+Tier 4 facts from query results only. It does not prevent external content from being
+captured into the graph. A developer who uses this flag expecting "no external content
+will enter my graph" is mistaken — they have only filtered what they see, not what
+is stored.
+
+**`paranoidCapture: true` in `~/.sia/config.json`**: quarantines all Tier 4 content at
+the capture pipeline's chunker stage. This is the hard guarantee. External content never
+reaches staging, never reaches the main graph, and appears only as a `QUARANTINE` entry
+in the audit log.
+
+**`--paranoid` CLI flag**: equivalent to `paranoid: true` on `sia_search` — retrieval
+filtering only, not capture-side isolation.
+
+If a developer asks for the strongest isolation from external content, direct them to
+`paranoidCapture: true` in config, not the query-time flag. Both can be used together
+for defence in depth.

package/skills/sia-pm-decision-log/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: sia-pm-decision-log
+description: Generates a chronological decision log from SIA with dates, rationale, and alternatives considered. Use for stakeholder reviews, project documentation, or tracking architectural decision history.
+---
+
+# SIA Decision Log
+
+Generate a formal decision log from the knowledge graph — useful for stakeholder reviews, audits, and project governance.
+
+## Usage
+
+```bash
+bun run ${CLAUDE_PLUGIN_ROOT}/src/cli/index.ts pm-report --type decisions --since 2026-01-01
+```
+
+## Format
+
+Each decision entry includes:
+- **Date** — when the decision was captured
+- **Decision** — what was decided
+- **Rationale** — why this option was chosen
+- **Alternatives Considered** — what was rejected and why
+- **Impact** — what this affects
+- **Status** — Active / Superseded / Under Review
+
+## Output
+
+Written to `DECISION-LOG.md` (or `--output <path>`).

package/skills/sia-pm-risk-dashboard/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: sia-pm-risk-dashboard
+description: Generates a technical risk dashboard from SIA — recurring bugs, conflicting decisions, fragile modules, scored by impact. Use for risk assessments, sprint planning, or identifying areas needing attention.
+---
+
+# SIA Risk Dashboard
+
+Generate a technical risk assessment with business impact scoring.
+
+## Usage
+
+```bash
+bun run ${CLAUDE_PLUGIN_ROOT}/src/cli/index.ts pm-report --type risks
+```
+
+## Risk Categories
+
+- 🔴 **Critical** — active bugs affecting users, unresolved conflicts
+- 🟡 **Moderate** — recurring issues, high-churn areas, stale conventions
+- 🟢 **Low** — documentation gaps, minor coverage issues
+
+## Output
+
+Written to `RISK-DASHBOARD.md` (or `--output <path>`).

package/skills/sia-pm-sprint-summary/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: sia-pm-sprint-summary
+description: Generates a sprint summary report from SIA in plain language — decisions made, bugs fixed, features delivered. Use for sprint reviews, status updates, or project manager briefings.
+---
+
+# SIA Sprint Summary
+
+Generate a PM-ready sprint summary from the knowledge graph.
+
+## Usage
+
+```bash
+bun run ${CLAUDE_PLUGIN_ROOT}/src/cli/index.ts pm-report --type sprint --since 2026-03-10 --until 2026-03-23
+```
+
+## Sections
+
+1. **Executive Summary** — 2-3 sentence overview
+2. **Key Decisions** — architectural choices with rationale (plain language)
+3. **Bugs Found & Fixed** — with business impact
+4. **Open Issues** — unresolved bugs with risk level
+5. **Risk Areas** — modules that need attention next sprint
+6. **Metrics** — entity counts, change velocity, bug rate
+
+## Output
+
+Written to `SPRINT-SUMMARY.md` (or `--output <path>`).

package/skills/sia-prune/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: sia-prune
+description: Removes archived entities from the SIA knowledge graph to reduce database size. Use when the graph grows large, after freshness reports show many stale entities, or for periodic maintenance.
+---
+
+# SIA Prune
+
+Hard-delete archived entities from the graph to free disk space and improve query performance.
+
+## Dry Run (Preview)
+
+See what would be pruned without deleting anything:
+
+```bash
+bun run ${CLAUDE_PLUGIN_ROOT}/src/cli/commands/prune.ts --dry-run
+```
+
+This shows each candidate with:
+- Entity name and type
+- Importance score
+- Days since last access
+
+## Confirm Prune
+
+Actually delete archived entities:
+
+```bash
+bun run ${CLAUDE_PLUGIN_ROOT}/src/cli/commands/prune.ts --confirm
+```
+
+## What Gets Pruned
+
+Only entities that are **archived** (`archived_at IS NOT NULL`) but **not invalidated** (`t_valid_until IS NULL`) are candidates. This distinction matters:
+
+- **Archived**: Entity decayed to irrelevance through the decay engine (low importance, not accessed recently)
+- **Invalidated**: Entity was explicitly superseded by newer information (keeps historical record)
+
+Pruning removes archived entities permanently. Invalidated entities are kept for bi-temporal history.
+
+## When To Use
+
+- When database size is growing large
+- After `sia-freshness` identifies many rotten entities
+- As periodic maintenance (monthly recommended)
+- Before exporting the graph to reduce export size

package/skills/sia-qa-coverage/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: sia-qa-coverage
+description: Analyzes test coverage gaps using SIA's knowledge graph — finds buggy areas without tests and high-churn modules with low coverage. Use when planning test improvements or before releases.
+---
+
+# SIA QA Coverage Analysis
+
+Identify areas that need more test coverage based on bug history and code changes.
+
+## How It Works
+
+SIA cross-references:
+- **Code entities** (functions, classes) from AST indexing
+- **Bug entities** from captured failures
+- **Test files** detected in the graph
+
+Areas with bugs but no corresponding test entities = coverage gaps.
+
+## Usage
+
+Ask the sia-qa-analyst agent or run:
+
+```
+sia_search({ query: "code entities <module>", node_types: ["CodeEntity"], limit: 50 })
+sia_search({ query: "bugs <module>", node_types: ["Bug"], limit: 20 })
+```
+
+Cross-reference to find gaps.

package/skills/sia-qa-flaky/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: sia-qa-flaky
+description: Tracks flaky test patterns using SIA — finds tests that fail intermittently and recurring test failures. Use when investigating test instability or prioritizing test reliability work.
+---
+
+# SIA Flaky Test Tracker
+
+Identify flaky tests by mining SIA's bug history for patterns:
+- Tests that appear as Bug entities multiple times (recurring failures)
+- Tests where Bug → Solution → Bug again (fixed then broke again)
+- Areas with high Bug creation + invalidation churn
+
+## How It Works
+
+```
+sia_search({ query: "test failure flaky intermittent", node_types: ["Bug"], limit: 30 })
+sia_at_time({ as_of: "<one_month_ago>", entity_types: ["Bug"] })
+```
+
+Compare Bug entities over time — tests that repeatedly fail and get fixed are flaky candidates.

package/skills/sia-qa-report/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: sia-qa-report
+description: Generates a QA-focused report from SIA — changes since last test cycle, risky areas, and recommended test priorities. Use before QA cycles, for test planning, or risk-based testing decisions.
+---
+
+# SIA QA Report
+
+Generate a testing-focused report from the knowledge graph.
+
+## Usage
+
+```bash
+bun run ${CLAUDE_PLUGIN_ROOT}/src/cli/index.ts qa-report --since 2026-03-15
+```
+
+## What It Shows
+
+1. **Changes since date** — decisions, code changes, new features grouped by module
+2. **Risk assessment** — bug density + change velocity per area
+3. **Bug activity** — bugs found, fixed, and still open
+4. **Test recommendations** — what to test first, specific test cases from bug history
+5. **Coverage gaps** — areas with code changes but no corresponding test changes
+
+## Output
+
+Written to `QA-REPORT.md` in the project root (or `--output <path>`).

package/skills/sia-reindex/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: sia-reindex
+description: Re-indexes the repository with tree-sitter to update SIA's knowledge graph with current code structure. Use after significant refactoring, file renames, or when code entities seem out of date.
+---
+
+# SIA Reindex
+
+Trigger a full or incremental re-index of the repository's code structure.
+
+## Steps
+
+Run the reindex command:
+
+```bash
+bun run ${CLAUDE_PLUGIN_ROOT}/src/cli/commands/reindex.ts
+```
+
+This will:
+1. Walk the repository file tree (respecting .gitignore)
+2. Parse each supported file with tree-sitter (25+ languages)
+3. Extract symbols, imports, and call relationships
+4. Update the knowledge graph with CodeSymbol, FileNode, and PackageNode entities
+5. Recompute PageRank for structural importance
+
+## When To Use
+
+- After major refactoring
+- When the graph seems stale or incomplete
+- After pulling significant changes from remote
+- When `sia-doctor` reports stale AST data

package/skills/sia-review-respond/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: sia-review-respond
+description: Responds to code review feedback using SIA's knowledge of past decisions, usage patterns for YAGNI checks, and conflict detection. Use when receiving PR feedback, review comments, or suggestions that may conflict with established conventions.
+---
+
+# SIA-Enhanced Code Review Response
+
+Respond to code review feedback grounded in SIA's decision history, usage edges (YAGNI checks), and convention records — argue from the graph, not from memory.
+
+## Checklist
+
+```
+- [ ] Step 1: Read all feedback without reacting
+- [ ] Step 2: Restate each item in your own words
+- [ ] Step 3: Query SIA for decisions/conventions related to each feedback item
+- [ ] Step 4: Evaluate — YAGNI via backlinks, conflict check via decision search
+- [ ] Step 5: Respond with graph citations
+- [ ] Step 6: Implement accepted items one at a time, test each
+- [ ] Post: Capture new decisions or convention changes to graph
+```
+
+## Workflow
+
+### Step 1 — Read Feedback (same as standard)
+
+Read all feedback without reacting.
+
+### Step 2 — Understand (same as standard)
+
+Restate each item in your own words.
+
+### Step 3 — Verify Against Graph (ENHANCED)
+
+For each feedback item:
+
+```
+sia_search({ query: "<feedback topic>", node_types: ["Decision", "Convention"], limit: 10 })
+sia_by_file({ file_path: "<file being reviewed>" })
+```
+
+Check:
+- Does a **past Decision** explain why the current approach was chosen?
+- Does a **Convention** mandate the current pattern?
+- Was the reviewer's suggestion **tried before and rejected?** (Check invalidated entities)
+
+### Step 4 — Evaluate (ENHANCED)
+
+For YAGNI checks — when a reviewer suggests adding a feature:
+
+```
+sia_backlinks({ node_id: "<entity_being_extended>" })
+```
+
+Check if any consumer actually needs the suggested extension. If zero backlinks use it → YAGNI.
+
+For conflict checks:
+
+```
+sia_search({ query: "decisions <topic>", node_types: ["Decision"], limit: 5 })
+```
+
+If the suggestion contradicts an established decision, present the conflict:
+
+> "This suggestion conflicts with [Decision: Use middleware for auth] which was established on [date] because [rationale]. Should we reconsider that decision, or keep the current approach?"
+
+### Step 5 — Respond (enhanced)
+
+**For response templates with graph citations:** See [pushback-patterns.md](pushback-patterns.md)
+
+When pushing back on feedback, cite SIA entities:
+
+> "The current implementation follows [Convention: Error handlers return structured JSON]. Changing this would break the established pattern documented in entity [id]."
+
+### Step 6 — Implement (same as standard)
+
+One item at a time, test each.
+
+### Post-Implementation — Capture (NEW)
+
+If the review led to new decisions or convention changes:
+
+```
+sia_note({ kind: "Decision", name: "<what changed based on review>", content: "<rationale>" })
+```
+
+## Key Principle
+
+**Don't argue from memory — argue from the graph.** SIA has the receipts: past decisions, conventions, and their rationale. Use them to validate or push back on feedback with evidence.

package/skills/sia-review-respond/pushback-patterns.md

@@ -0,0 +1,90 @@
+# Evidence-Based Pushback Patterns
+
+Templates for responding to code review feedback using SIA graph citations. The principle: don't argue from memory — argue from the graph.
+
+## Pattern 1: Convention Conflict
+
+**When:** Reviewer suggests a change that violates an established convention.
+
+**Query:**
+```
+sia_search({ query: "<convention area>", node_types: ["Convention"], limit: 5 })
+```
+
+**Response template:**
+> The current implementation follows **[Convention: {name}]** (entity {id}, captured {date}): "{convention content}". The suggested change would deviate from this established pattern. Should we update the convention, or keep the current approach?
+
+**Key:** Always offer to update the convention. Conventions aren't immutable — but changes should be explicit.
+
+## Pattern 2: Decision Rationale
+
+**When:** Reviewer questions why something was done a certain way.
+
+**Query:**
+```
+sia_search({ query: "<decision area>", node_types: ["Decision"], limit: 5 })
+```
+
+**Response template:**
+> This approach was chosen based on **[Decision: {name}]** (captured {date}): "{rationale}". Alternatives considered were: {alternatives}. The deciding factor was: {key_reason}.
+
+**Key:** Include the alternatives that were considered — this shows the decision was deliberate, not accidental.
+
+## Pattern 3: YAGNI via Backlinks
+
+**When:** Reviewer suggests adding a feature or generalization.
+
+**Query:**
+```
+sia_backlinks({ node_id: "<entity_being_extended>" })
+```
+
+**Response template (zero consumers):**
+> I checked the usage graph for `{entity}` — it currently has **{N} consumers**: {list or "none"}. Adding {suggested feature} would be unused by any current consumer. Should we defer this until there's a concrete use case?
+
+**Response template (few consumers):**
+> The usage graph shows {N} consumers of `{entity}`: {list}. None of them use {suggested pattern}. This might be YAGNI — want to revisit when a consumer needs it?
+
+## Pattern 4: Tried Before
+
+**When:** Reviewer suggests an approach that was previously tried and rejected.
+
+**Query:**
+```
+sia_search({ query: "<suggested approach>", node_types: ["Decision"], limit: 10 })
+```
+
+Look for entities with `t_valid_until` set (invalidated decisions).
+
+**Response template:**
+> This approach was previously tried — see **[Decision: {name}]** (captured {date}, invalidated {invalidation_date}): "{why it was rejected}". What's different now that would make this approach succeed?
+
+**Key:** Always ask what changed. Sometimes circumstances genuinely are different — the question prevents dismissing valid suggestions.
+
+## Pattern 5: Accept with Citation
+
+**When:** Reviewer's feedback is valid and should be implemented.
+
+**Response template:**
+> Good catch — this aligns with **[Convention: {name}]** which I should have followed. Implementing now.
+
+Or if it reveals a gap:
+
+> You're right. I'm capturing this as a new convention:
+> ```
+> sia_note({ kind: "Convention", name: "<new pattern>", content: "<description>" })
+> ```
+
+## Anti-Pattern: Blind Agreement
+
+**Never agree with feedback without verifying it first.** Even valid-sounding suggestions may conflict with established decisions. Always check the graph before accepting or rejecting.
+
+## Quick Reference
+
+| Situation | Query | Response Strategy |
+|---|---|---|
+| "Change this pattern" | `sia_search` for Convention | Cite convention, offer to update |
+| "Why did you do it this way?" | `sia_search` for Decision | Cite decision + alternatives |
+| "Add this feature" | `sia_backlinks` | Show consumer count (YAGNI check) |
+| "Use approach X instead" | `sia_search` for invalidated entities | Show if tried-and-rejected |
+| "Good point, fix this" | Verify with `sia_by_file` | Accept with citation, capture if new |