DEV Community: Siddharth Pandey

Your DB Is Still Red After Adding a Cache — Here's Why

Siddharth Pandey — Tue, 23 Jun 2026 12:21:17 +0000

You deployed a cache in front of your database three weeks ago. The DB is still running at 90% utilization. Traffic doubled last month and you're wondering if the cache is doing anything at all.

It is — just not as much as you expected, because cache hit rate is not something you configure. It emerges from two things: how much of your working set fits in memory, and how skewed your access patterns are.

Paperstack is a free system design simulator that makes this visible. Sketch an architecture, press play, watch utilization numbers and node colors update live. The demo below walks through the cache problem using it.

Hit Rate Isn't a Setting

A cache absorbs reads by serving them from memory instead of forwarding them to the database. The fraction it absorbs — hit rate — depends on one thing: whether the data a request needs is in memory.

Two variables determine that:

Working-set vs memory. If your active data is 100,000 keys and your cache holds 50,000, only half the requests can possibly hit — the rest miss and forward to the DB. Your cache isn't broken. It's undersized for the working set.

Access skew. If 80% of requests hit 10% of keys (common in social or content workloads), a much smaller cache can achieve a high hit rate because the hot keys stay warm and rarely get evicted. Paperstack models this directly via the skew parameter on the Cache node: with an LFU eviction policy, higher skew boosts hit rate beyond raw memory coverage. With LRU, skew gives no benefit — the eviction algorithm doesn't take access frequency into account, so cold pages get evicted as readily as hot ones.

This is why you can't just set hitRate: 0.9 in the config panel — Paperstack doesn't expose hit rate as a field. You set memory and workingSet; hit rate is computed. If the simulation let you enter a hit rate directly, it would be lying to you about what your architecture actually does.

The Comparative in Action

Here's the experiment worth running in Paperstack: sketch Traffic → App → Cache → Database. Run the simulation. Watch which nodes go red.

With cache memory smaller than workingSet, most reads miss and forward to the DB. The DB stays red. The cache stays green — it has throughput headroom, it's just not absorbing much.

Now increase the cache memory past the working-set size. The hit rate climbs. Fewer reads reach the DB. At some threshold the DB color shifts from red to orange to green — and a different node becomes the bottleneck. Maybe the App Server. Maybe the cache's own throughput cap.

This is what Paperstack calls the comparative: when you change one variable, the bottleneck doesn't disappear — it moves. That relocation is the lesson. Scaling the cache fixed your DB problem and revealed your next one.

The inverse is just as instructive. Remove the Cache node and rerun. Watch the DB immediately redline. This is how you build intuition for what a cache is actually doing — not by reading about hit rates, but by watching the utilization delta before and after.

When Write Policy Matters

Paperstack exposes three write patterns on the Cache node: Cache-aside, Write-through, and Write-behind. The choice affects both latency and what happens when you kill the cache node.

Cache-aside (the default) separates reads from writes entirely. Reads check the cache first; misses go to the DB. Writes bypass the cache and go directly to the DB. The cache is populated on read-miss, not on write. Kill the cache: reads start missing entirely, DB load spikes, but the write path was already going to DB — no disruption there.

Write-through keeps the cache and DB in sync on every write. Writes pay the cache's latency and the DB's latency on the write path, making writes more expensive than cache-aside. Kill the cache: reads fall through to DB, but every write was already reaching the DB, so nothing is lost.

Write-behind is where the kill scenario gets interesting. In this mode, the cache absorbs writes entirely — they never reach the DB during normal operation. Only read-misses reach the DB. The DB is effectively shielded from the write load.

Kill the cache node in write-behind mode: Paperstack's passThroughOnKill behavior makes the cache transparent — all traffic falls straight through. The DB suddenly receives the write workload that was never reaching it before. If the DB was sized assuming writes were handled by the cache, it may not have the writeCap headroom to absorb the sudden change. The simulation shows this directly as DB utilization spiking and requests dropping.

This failure mode is invisible on a static architecture diagram. The diagram shows cache → DB regardless of write policy. The simulation shows what breaks.

Conclusion

The cache-doesn't-help problem is usually a mismatch between memory and working set, not a configuration error. Once hit rate is computed from real inputs rather than typed in, the DB utilization behavior makes sense.

Paperstack makes the relationship between working-set size, cache memory, write policy, and DB utilization visible without deploying anything. Sketch the architecture, tune the numbers, kill nodes, and watch the bottleneck move. When the DB finally turns green, you know exactly why.

Try it at Paperstack — it runs in the browser, no account needed.

Key Takeaways

Cache hit rate emerges from memory vs workingSet and access skew — it's computed, not configured. Undersizing cache memory caps hit rate regardless of traffic volume.
The comparative (change one variable, watch the bottleneck move) is how you build cache intuition: adding cache makes the DB green, revealing the next bottleneck.
LFU eviction benefits high-skew workloads (popular keys stay warm); LRU does not — skew only matters with the right eviction policy.
Write-behind shields the DB from writes during normal operation; kill the cache and the DB suddenly receives the write load it was never sized for.
Write-through and Cache-aside are safe to kill (writes were already reaching DB); write-behind changes the DB's workload profile on failure.

Why Your Reranker Isn't Helping Your RAG Pipeline (And How to Prove It)

Siddharth Pandey — Sun, 21 Jun 2026 07:57:40 +0000

You add a cross-encoder reranker to your RAG pipeline, measure answer quality on a test set, see a marginal improvement on 3 of 8 questions, and ship it. Six weeks later your p99 retrieval latency has climbed 200ms per query and you're paying Cohere API costs on every call. Nobody has revisited the decision because there's no data to revisit. The reranker is in the pipeline now. It probably helps.

That "probably" is the problem. RAGScope · npm gives you a per-query metric that tells you exactly whether your reranker is earning its cost — or actively making things worse.

What "Reranker Gain" Actually Measures

When your RAG app runs a query, it emits OpenTelemetry spans: a retrieval span carrying chunk IDs, scores, and content; an optional reranking span; and an LLM span containing the full prompt text. RAGScope receives these via OTLP on port 4321 and analyzes the full trace end-to-end.

The rerank-gain metric answers one question: did the reranker pull the chunks the LLM actually used toward the top of the list? RAGScope compares each chunk's retrieval rank (its position before reranking) against its reranked rank (its position after), then measures the average rank improvement of the chunks that ended up in the LLM's prompt. A chunk that was retrieved 8th but reranked to 2nd and appeared in the prompt counts as a large positive gain. A chunk that was retrieved 2nd, reranked to 9th, and got dropped from the prompt counts as a loss.

The metric only appears in the score when the trace contains a reranker span. When it does, the weights renormalize automatically — precision drops from 40% to 35%, efficiency from 30% to 25%, and rerank-gain takes a 15% slice alongside uniqueness at 15% and coverage at 10%. Traces without a reranker span score exactly as before, so you can compare directly.

Reading the Signal — What Good and Bad Look Like

A reranker earning its cost looks like this:

│  ✓  rerank-gain  88  █████████░  used chunks promoted avg +3.0 ranks

The chunks the LLM actually used were promoted an average of 3 positions by the reranker. That means the reranker is doing its job: surfacing the relevant material higher so it reaches the prompt and lands near the edges where the LLM attends most.

A reranker not earning its cost:

│  ✗  rerank-gain  25  ███░░░░░░░  used chunks demoted avg -2.0 ranks
│  → Reranker is not surfacing the chunks the LLM actually uses

The chunks the LLM used were demoted by the reranker. They reached the prompt despite the reranker, not because of it. The reranker added latency and cost and then moved the useful material further back in the queue.

The key insight is that RAGScope measures gain on the chunks that actually appeared in the LLM's prompt — not on the full ranked list. A reranker can shuffle 10 results around impressively while consistently pushing the 3 chunks the LLM uses toward position 7, 8, and 9. That's not a reranker working; that's a reranker actively degrading retrieval for this query type.

What to Do When the Reranker Is Hurting

The first step is query segmentation. RAGScope scores every query your pipeline processes individually. Run it for a day and you'll have a distribution of rerank-gain scores broken down by query type. If your reranker earns a score of 80+ on factual lookups but consistently scores below 30 on comparison queries, you have a model-query-type mismatch, not a broken reranker.

The second step is checking your reranker's training domain. Cross-encoders trained on MS MARCO work well for web-search-style queries. If your documents are internal API docs, legal contracts, or medical literature, the reranker may be applying a relevance signal that's semantically misaligned with your content. A low rerank-gain score on a specific document type is a strong signal to evaluate a domain-specific model.

If the rerank-gain score is consistently low across query types, the simplest intervention is removing the reranker entirely and routing that latency budget into a higher TOP_K with tighter similarity thresholds. RAGScope's precision metric will tell you immediately whether that trade works: if precision improves and efficiency holds, you've recovered the latency without losing quality.

Conclusion

A reranker is not always additive. It introduces latency, API cost, and an additional failure mode on every query — and most teams have no per-query signal to determine whether it's paying for itself. Aggregate quality metrics on a test set don't expose query-level degradation.

RAGScope's rerank-gain metric gives you that signal query by query, live in your terminal as the pipeline runs. Start it with npx ragscope start, add OTLP instrumentation to your retrieval and reranker calls, and you'll know within the first few queries whether the reranker is earning its place in your pipeline.

GitHub · npm

Key Takeaways

rerank-gain measures the average rank improvement of the chunks the LLM actually used — not the full ranked list, which can mask per-query degradation.
The metric only appears when the trace contains a reranker span; weights renormalize automatically (precision 35%, efficiency 25%, rerank-gain 15%, uniqueness 15%, coverage 10%).
A reranker with consistently negative rerank-gain is demoting the chunks the LLM uses — adding cost and latency for a net-negative retrieval outcome.
Query segmentation reveals whether the reranker works for some query types but not others, pointing to model-query-type mismatch.
If rerank-gain is consistently low across query types, removing the reranker and increasing TOP_K is often a better trade — RAGScope's precision score will validate it immediately.

Fix N+1 Trigger Patterns Where Lambda Functions Hammer the Same DynamoDB Partition Key

Siddharth Pandey — Sat, 20 Jun 2026 18:15:52 +0000

You add a sixth Lambda trigger to your OrderEvents table, deploy it, and within 20 minutes your SLA dashboard goes red. Latency on order writes jumps from 4ms to 40ms. The function itself is fine. The table is fine. The problem is that five other Lambdas are already hitting the same partition key on every write, and you just made it six. DynamoDB's internal partition throttling doesn't care that each function looks clean in isolation.

This is an N+1 trigger problem, and your AI coding assistant cannot catch it. Not because it lacks intelligence, but because the fact that five Lambdas already target that table lives in your AWS account and your full codebase — not in the file your assistant has open.

Infrawise · npm

Why the LLM Can't See the Pattern

When you ask Claude to write a new order processing Lambda, it reads the file you have open and generates code that looks correct — because in the context of that one file, it is correct. It doesn't know about ProcessRefundsLambda, NotifyFulfillmentLambda, SyncInventoryLambda, UpdateAnalyticsLambda, and AuditTrailLambda, all of which you wrote in previous sprints and which all write to the Orders table.

This is a category of failure that model quality doesn't fix. A better model produces a more fluent explanation for why your latency spiked. The fact that five functions converge on the same table is a lookup, not a prediction. The source of truth is a combination of your code (which functions exist) and your infrastructure (what they access).

Infrawise draws that boundary explicitly. It extracts the answer from your code using AST parsing and from your infrastructure using API calls, then hands that graph to the model as structured context — it never generates the answer.

How Infrawise Traces Trigger Chains to the Same Table

When Infrawise scans your repository, it uses ts-morph to walk every CallExpression in every source file. It's not searching for the string "DynamoDB" — it matches call structure against a known set of SDK patterns in a DYNAMO_OPERATIONS set: both v2 method names (getItem, query, putItem, updateItem, deleteItem, batchWriteItem) and v3 command classes (QueryCommand, PutItemCommand, UpdateItemCommand, DeleteItemCommand). Each matched call becomes an extracted operation: this function performs this operation against this table.

That list feeds into a SystemGraph. Nodes represent tables, functions, indexes, queues, and topics. Edges represent query, scan, and write relationships. The graph is what makes the N+1 pattern visible: not just "six functions exist" and "a table exists," but "six functions all write to Orders with no distribution across paths."

The HotPartitionAnalyzer walks the graph and fires when a table receives five or more distinct access edges from separate code paths. The threshold is configurable per-table via hotPartitionThresholds in infrawise.yaml — Issue #57 resolved false positives on high fan-in systems by making this a per-table setting rather than a single global value. A finding looks like:

Medium severity
Potential hot partition detected on DynamoDB table "Orders"
  Table "Orders" is accessed by 6 distinct code paths, which may create
  hot partition issues at scale. High access concentration on the same
  partition key can throttle requests.
  Recommendation: Consider adding a random suffix or timestamp to partition
  keys (write sharding). Use DynamoDB DAX for read-heavy workloads.

This runs deterministically. Feed it the same graph, get the same findings. There's no sampling temperature involved.

The infrawise check --fail-on medium command gates CI on this finding. Since HotPartitionAnalyzer emits medium severity, you need --fail-on medium (the default --fail-on high won't catch it). When violations are found, infrawise check exits with code 1 — your build fails before the sixth Lambda merges, and the engineer who wrote it sees the finding in the PR, not on a latency dashboard at 11pm.

Fixing It — Restructuring the Key or Sharding the Access Pattern

Once Infrawise surfaces the pattern, you have two practical options.

Write sharding adds a random suffix to the partition key — distributing writes across logical partitions. Reads require scatter-gather or a deterministic suffix derived from the order ID. This is the right choice when all six functions are pure writers and reads are handled by a separate query path.

Access pattern separation restructures which functions need direct table access at all. If SyncInventoryLambda and UpdateAnalyticsLambda are consuming state that flows through the Orders table, they shouldn't write to it directly — they should react to a DynamoDB stream and write to their own tables. The fan-in often exists because multiple services treat the same source-of-truth table as a synchronization point when they should be downstream consumers.

The analyze_function tool helps here. Point it at any function and it traces the full access path: which tables the function reads and writes, which indexes it uses, what event shapes trigger it, and what queues or topics it publishes to. That trace makes it clear which functions can be moved to stream consumption and which genuinely need direct write access.

Conclusion

The N+1 trigger problem is invisible to any tool that works only from your open files. It's not a reasoning failure — no amount of context about a single Lambda reveals that five others already saturate the same table. That fact lives in the intersection of your code and your infrastructure.

Infrawise puts that intersection in a graph, runs deterministic analyzers over it, and surfaces the finding before it becomes a production incident. The model's job is to decide what to do — restructure the key, introduce a stream, separate the access pattern. The detection is never generated; it's extracted.

If your AI assistant is writing Lambda functions against DynamoDB, give it the access graph first: GitHub · npm.

Key Takeaways

A hot partition problem requires knowing how many code paths hit the same table — that fact lives in your AWS account and your full codebase, not in the file your AI assistant has open.
Infrawise's HotPartitionAnalyzer counts distinct code paths hitting each DynamoDB table and fires at a configurable threshold, with per-table overrides via hotPartitionThresholds in infrawise.yaml.
Hot partition findings emit medium severity; use infrawise check --fail-on medium to gate CI builds on them (the default --fail-on high won't catch them).
analyze_function traces the full access path for any function — tables, indexes, event shapes, queues — making it easy to separate writers from downstream consumers.
Write sharding and event-stream separation are the two practical fixes; which one to pick depends on whether converging functions genuinely need to write or are just consuming state.

Stop Paying For Retrieval Latency On Chunks You Never Use In The Prompt

Siddharth Pandey — Tue, 16 Jun 2026 08:12:31 +0000

Your pipeline fetched 10 chunks. Your LLM saw 3.

You set TOP_K=10 on your vector store. Ten candidate chunks means more signal for the model — that's the logic. Then you run npx ragscope and the audit prints:

  WARN   51/100  █████░░░░░  my-rag-service
  │  "what are the pricing tiers?"
  │
  │  ✗  precision     30  ███░░░░░░░  3/10 chunks used
  │  ✗  efficiency    30  ███░░░░░░░  70% tokens wasted
  │  ✓  uniqueness   100  ██████████  chunks are distinct
  │  ✓  coverage     100  ██████████  all chunks scored
  │
  │  → Reduce TOP_K 10→3 (only 3 chunks reached LLM)
  │  → 70% of retrieved tokens never reached the LLM
  │

Three of ten chunks made it into the final prompt. You paid for ten round-trips to the vector store and seven went nowhere. The other seven were fetched, scored, and discarded somewhere between your retrieval step and your prompt assembly code.

This is the gap ragscope (npm) was built to surface.

Where the Chunks Disappear

Retrieval and prompt assembly are separate steps, but most teams treat them as one. The gap is where the waste lives.

A typical RAG pipeline:

Embed the query
Fetch TOP_K chunks from the vector store
(Optional) Rerank
Assemble the prompt — filter by score threshold, truncate to fit the context window
Send to the LLM

Step 4 is where chunks disappear. Post-retrieval filtering — a score threshold, a hard token budget, a deduplication pass — silently drops chunks you already paid to retrieve. If your prompt assembly filters out anything below a certain confidence score and your vector store returns six chunks that don't clear it, those six fetches were wasted. The network round-trip still happened. The latency still accumulated.

The problem compounds over time. TOP_K=10 gets set as a safe default, the pipeline ships, and the setting never gets revisited. LLM eval scores look fine because the three chunks that do reach the prompt are the right ones. The waste is invisible in your evals — it only shows up in latency and cost.

Vector stores typically scale retrieval latency with TOP_K. Fetching ten results takes measurably longer than fetching three, especially at tail latencies. When seven of those ten are discarded before the prompt, you're paying that latency premium on every query for nothing.

How ragscope Measures `precision`

ragscope runs as a local server (default port 4321) and receives spans from your pipeline via OTLP at http://localhost:4321/v1/traces. No changes to your RAG code needed — configure your OpenTelemetry exporter to point there.

When both a retrieval span and an LLM span arrive for the same trace, ragscope compares them. The key field is inContext on each RagChunk. It inspects the full text of the LLM span's assembled prompt and checks whether each retrieved chunk's content appears in it — positionally, by string match. A chunk either appears in the prompt or it doesn't. No LLM, no heuristics, no sampling.

precision starts as:

base = (chunks where inContext is true / total retrieved chunks) × 100

There's one additional penalty: if high-retrieval-rank chunks land in the middle of a long context window — the zone where LLM attention typically falls off — ragscope subtracts 12 points per buried chunk, capped at 36. This is the lost-in-the-middle detection. A pipeline where 3/10 chunks are used but two of those three are buried mid-context will score lower than one where the same 3 chunks sit at the prompt edges.

When the base falls below 60, ragscope generates a specific recommendation with the exact numbers: Reduce TOP_K 10→3 (only 3 chunks reached LLM). It prints this directly below the score bars, in the terminal, at the time the trace arrives — not in a cloud dashboard after a deploy.

efficiency is a related metric: the fraction of retrieved tokens that reached the LLM. If precision is 30 and your chunks are roughly uniform in size, efficiency will also be around 30 — meaning 70% of the tokens you transferred from the vector store never appeared in a prompt. That shows up in retrieval latency and, depending on your pipeline, in processing time downstream.

Tuning TOP_K Based on the Audit

Once you have precision data, tuning is mechanical.

Follow the recommendation. ragscope prints Reduce TOP_K 10→3 because Math.max(used_chunks, 3) gives you the minimum viable retrieval count with a floor of 3. Start there and re-run the audit against a few real queries.

Check efficiency alongside. Low efficiency paired with low precision means your unused chunks are large — a chunking strategy problem as much as a TOP_K problem. If efficiency is high but precision is low, your unused chunks are small and the token cost is modest; fixing TOP_K will mostly recover the latency.

Check uniqueness too. If the chunks that do reach your prompt include near-duplicates, the uniqueness metric will flag them. Two near-duplicate chunks in the prompt means one is redundant regardless of your TOP_K setting — that's a deduplication-at-ingest problem, not a retrieval count problem. ragscope computes overlap between chunk pairs and surfaces high-overlap counts in the audit output.

The typical path after a low-precision audit:

Audit shows 3/10 chunks used — follow the Reduce TOP_K 10→3 recommendation
Re-run against real queries — precision should move above 75 (PASS)
If uniqueness also flagged duplicates, fix chunking and re-run
If efficiency is still low after fixing TOP_K, chunks may be too large for the token budget

Going from TOP_K=10 to TOP_K=3 on a pipeline that was only ever using 3 chunks means 70% fewer vector store round-trips on every query. No model changes, no prompt rewriting, no reranker added.

The Number You Should Check First

The assumption that more retrieval means better answers is almost never validated against what the model actually sees. TOP_K defaults get set once and forgotten. Eval scores stay flat because the chunks that do reach the LLM are the right ones — the waste doesn't affect quality, just cost and latency.

npx ragscope gives you precision, efficiency, and uniqueness in the time it takes to run a dev command. If you haven't checked what fraction of your retrieved chunks survive to the prompt, that's the number to look at first.

GitHub · npm

Key Takeaways

precision measures what fraction of retrieved chunks appear in the final LLM prompt — anything below 60/100 triggers a Reduce TOP_K recommendation with exact numbers
Vector store round-trips typically scale with TOP_K; fetching chunks you discard is pure overhead with no quality benefit
ragscope detects in-prompt chunk presence by matching content against the OTLP LLM span's prompt text — deterministic, no LLM needed
Low efficiency paired with low precision points to a chunking strategy problem, not just a TOP_K problem
Low uniqueness means near-duplicate chunks in the prompt — fix at ingest, not by adjusting retrieval count

Why Infrawise Uses Deterministic Analysis Instead of an LLM

Siddharth Pandey — Sat, 13 Jun 2026 10:58:44 +0000

Ask your AI coding assistant which Global Secondary Indexes exist on your Orders table. It will read your repository, find a few QueryCommand calls, and answer — fluent, specific, and confident. It also has no way to know. GSI definitions live in AWS, not in your source files. The model isn't lying; the fact simply isn't available to it, so it generates the most statistically plausible substitute and delivers it in the same tone it uses for things it actually knows.

That failure mode is why Infrawise (npm) — an MCP server that gives AI coding assistants infrastructure context — contains no LLM calls at all. Every answer it serves comes from AST parsing, schema introspection, rule-based analyzers, and graph correlation. The LLM is only ever a consumer of that context, never a producer of it. This post is about why that boundary exists, and what it looks like in code.

Infrastructure questions are lookups, not generation

There are two kinds of questions you can ask a tool. "How should I model sessions in DynamoDB?" is a judgment question — many defensible answers, context matters, an LLM is genuinely useful. "Does the Sessions table have a GSI on userId?" is a fact question. It has exactly one correct answer, and that answer is sitting in a DescribeTable response.

When you route a fact question through a generative model, you convert a lookup with a perfectly accurate source into a prediction with an unknown error rate. The motivating examples in the Infrawise README are all of this shape: an assistant suggesting a .scan() on an Orders table with 50 million rows, recommending a GSI on status that already exists, or not noticing that five functions are already hammering the same partition key. None of these are reasoning failures. They are missing-fact failures, and no amount of model quality fixes them — a better model just produces a more convincing wrong answer.

So Infrawise draws a hard line: facts get extracted deterministically, and the model receives them through MCP tool calls instead of guessing.

What deterministic extraction looks like

Infrawise builds its picture of your system from three sources, none of which involve a model.

Your code, through the compiler's eyes. scanRepository() in src/context/index.ts loads the repo with ts-morph — using your own tsconfig.json when one exists — and walks every CallExpression node in every source file. It doesn't regex for the word "scan". It matches call structure against known client patterns: a DYNAMO_OPERATIONS set covering both SDK v2 method names (query, scan, getItem) and SDK v3 command classes (ScanCommand, QueryCommand, PutItemCommand), query/execute/exec calls on PostgreSQL and MySQL clients, and MongoDB collection methods — where find and aggregate are classified as scan-type operations and the rest as queries. The output is a list of extracted operations: this function performs this operation type against this table.

Your databases, through their own catalogs. The PostgreSQL adapter doesn't ask a model to summarize your schema. It runs the same introspection queries you would run by hand — information_schema.tables for tables, information_schema.columns for columns, pg_indexes for indexes, and the constraint tables for keys. The docs recommend pointing it at a dedicated read-only user, and the DynamoDB side needs only dynamodb:ListTables and dynamodb:DescribeTable permissions. What comes back isn't a description of your schema; it is your schema.

Correlation, through a graph. Both streams land in a SystemGraph: typed nodes for tables, functions, indexes, queues, topics, lambdas, buckets, secrets, parameters, and log groups, connected by typed edges like query, scan, and uses_index. The graph is what turns two boring fact lists into something an analyzer can interrogate — not just "this table exists" and "this function scans something," but "listAllOrders() scans the Orders table, and no index covers that access."

Rules, not vibes

The analysis layer is where most tools would reach for a model — and where Infrawise stays deterministic. The analyzer index exports 27 rule classes covering DynamoDB, PostgreSQL, MySQL, MongoDB, SQS, S3, Lambda, RDS, secrets, log retention, and Terraform drift. Each one is an ordinary class with an analyze(graph) method that walks the graph and emits findings.

FullTableScanAnalyzer follows scan-type edges to DynamoDB table nodes and emits a high-severity finding naming the table and every calling function. MissingGSIAnalyzer flags tables that receive query edges but have no uses_index edge — medium severity, because it might be intentional. HotPartitionAnalyzer fires when a table is accessed by five or more distinct code paths (the threshold is a constructor parameter, defaulting to 5).

Two properties fall out of this design that a model can't give you:

Findings are testable. Every analyzer is a pure function of the graph. Feed it a fixture, assert on the output, done. There's no eval harness, no sampling temperature, no "run it three times and hope." If FullTableScanAnalyzer regresses, a unit test catches it.

Failures are contained and honest. runAllAnalyzers() wraps each analyzer in its own try/catch — one analyzer crashing logs a warning while the rest keep running. The combined findings are then sorted by a fixed severity order: high, medium, low, and notably verify — a severity that exists precisely so a deterministic system can say "I detected a pattern but can't confirm the intent" instead of bluffing. An LLM has no equivalent of verify; everything it says arrives with the same confident fluency.

The LLM is the consumer, not the analyst

None of this means LLMs are useless here. It means they belong at a specific layer. Infrawise exposes the graph and findings through 15 MCP tools: get_infra_overview for a quick snapshot, analyze_function to trace a single function's tables, queues, secrets, and trigger event shapes, suggest_gsi to generate a ready-to-use GSI definition for a table and attribute, postgres_index_suggestions for index advice, and so on. The assistant decides when to ask and what to do with the answer. It never produces the answer.

The plumbing is deliberately boring: analysis results are cached as JSON files under .infrawise/cache, and the infrawise stdio process your editor spawns re-runs the analysis when the cache is older than 24 hours. Run infrawise start --claude once and it writes .mcp.json so Claude Code reconnects automatically on every future launch.

This division of labor generalizes well beyond one project. The model handles intent ("the user wants this query to be cheaper") and synthesis ("given these findings, here's the migration plan"). The deterministic layer handles every claim that has a ground truth. The test is simple: if asking the same question twice should yield the same answer, don't generate the answer — look it up.

If your AI assistant writes code against AWS or a database, give it facts instead of letting it guess: GitHub · npm.

Key takeaways

A fact question routed through a generative model turns a lookup with a perfect source into a prediction with an unknown error rate. Route facts around the model, not through it.
AST-level extraction (ts-morph walking CallExpression nodes) catches what schema introspection alone can't see — which function scans which table, and how.
Rule-based analyzers are unit-testable and fail loudly per rule; model-based analysis is neither.
A deterministic system can emit a verify severity when it isn't sure. A model can't reliably tell you when it's guessing.
Put the LLM at the boundary: it consumes structured facts over MCP and decides what to do next — it never gets to invent the facts.

Give Your AI Assistant Infrastructure Eyes Before It Writes Another Query

Siddharth Pandey — Tue, 09 Jun 2026 18:18:02 +0000

You asked Claude Code to add pagination to your order history endpoint. It generated a clean function — listOrdersByUser() — using a DynamoDB Scan with a Limit parameter. It compiled. Tests passed. You shipped it.

Three days later your AWS bill had a line item you didn't recognize: 47 million read capacity units consumed in 72 hours. The Orders table has 50M rows. Scan reads every one of them regardless of Limit — Limit only controls how many results come back, not how many items DynamoDB reads.

Claude Code didn't know your table had 50M rows. It didn't know you had a GSI on userId. It guessed, and the guess was expensive.

infrawise · npm

What AI Assistants Don't Know About Your Infrastructure

AI coding assistants read your source files. They understand function signatures, TypeScript types, and import chains. What they cannot see is the infrastructure those functions run against.

When Claude Code looks at a file that calls dynamoClient.scan({ TableName: "Orders" }), it has no idea that:

The Orders table has 50M items
There is already a GSI named userId-index on the userId attribute
Three other functions are already using Query against that same GSI
The Sessions table is accessed by 6 separate code paths, making it a hot partition candidate

Without that context, the assistant fills the gap with generic patterns. It recommends Scan because it has no reason not to. It suggests adding a GSI on status because it doesn't know one exists. It writes SELECT * because it has no idea which columns are expensive to pull.

This isn't a bug in the model. It's a missing input. The model was never given your infrastructure.

What Happens When infrawise Is in the Loop

infrawise statically analyzes your codebase, your DynamoDB tables, and your PostgreSQL schemas, then exposes that context to your editor through MCP. Claude Code gets 15 tools that answer questions like: which tables exist, what are their partition keys and sort keys, which GSIs are already defined, which functions are already scanning, and which patterns are flagged as high severity.

The difference in output is concrete. Here's what infrawise surfaces before any code gets written:

Findings  3 total

  1.  HIGH   Full table scan detected on DynamoDB table "Orders"
             listAllOrders() scans without any filter — reads every item in the table.
             → Replace Scan with Query using a partition key or add a GSI.

  2.  MED    PostgreSQL table "users" has no index on column "email"
             Filtering on "email" causes sequential scans.
             → CREATE INDEX CONCURRENTLY idx_users_email ON users(email);

  3.  MED    DynamoDB table "Sessions" accessed by 6 distinct code paths
             Hot partition risk — multiple functions hammer the same key.
             → Review access patterns and consider partition key design.

When Claude Code has this context, its suggestions change. It knows userId-index exists and recommends Query against it instead of Scan. It knows the email column has no index and includes the exact CREATE INDEX CONCURRENTLY statement rather than a generic suggestion. It knows which functions are already hitting a partition hard before it adds another one.

The recommendations become specific to your actual tables, not generic advice copied from documentation.

infrawise does none of this with an LLM. The analysis is entirely deterministic: TypeScript AST parsing via ts-morph for the code graph, schema introspection for the database layer, rule-based analyzers for pattern detection, and graph correlation to connect code paths to tables. No model is involved in the analysis — models are only consumers of the output.

Wiring It Up — infrawise start --claude

npm install -g infrawise
cd your-project
infrawise start --claude

On first run, infrawise asks a few questions and generates infrawise.yaml. It then scans your AWS services, databases, and codebase, writes .mcp.json so your editor auto-connects, and opens Claude Code with all 15 MCP tools ready.

Every session after that:

claude

No infrawise command needed. The editor manages the MCP connection. Analysis is cached for 24 hours; when the cache goes stale, infrawise stdio — spawned automatically at session start — refreshes it. File changes are detected within the session and the code graph updates automatically without re-running AWS extraction.

For PostgreSQL, infrawise uses a read-only connection. Create the user with these four statements:

CREATE USER infrawise_ro WITH PASSWORD 'yourpassword';
GRANT CONNECT ON DATABASE yourdb TO infrawise_ro;
GRANT USAGE ON SCHEMA public TO infrawise_ro;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO infrawise_ro;

If you want to check findings without opening an editor:

infrawise analyze --severity high
infrawise analyze --severity high --output report.md

The --severity flag accepts high, medium, low, or verify. The --output flag saves findings as a markdown report.

Conclusion

The problem isn't that AI coding assistants write bad code. The problem is that they write code for an infrastructure they've never seen. A Scan on an empty dev table and a Scan on a 50M-row production table look identical in source — the model has no way to tell them apart unless something provides that context.

infrawise makes that context available deterministically, before the code gets written. The assistant stops guessing about your GSIs, your partition keys, and your missing indexes because it no longer needs to guess.

Try it: GitHub · npm

Key Takeaways

AI coding assistants have no knowledge of your actual infrastructure — they infer from source files and fill gaps with generic patterns
A Scan with Limit still reads every item in DynamoDB before applying the limit — the model won't know this unless it knows your table's access patterns
infrawise exposes your exact schemas, GSIs, partition keys, and flagged patterns to your editor through MCP — 15 tools Claude Code can query before writing a single line
All analysis is deterministic: TypeScript AST parsing, schema introspection, rule-based detection — no LLM in the analysis path
Setup is one command: infrawise start --claude generates config, writes .mcp.json, and opens your editor with full context ready

Add a PASS/WARN/FAIL Quality Gate to Your RAG Pipeline in 30 Seconds

Siddharth Pandey — Sat, 06 Jun 2026 11:34:50 +0000

You deployed a RAG chatbot. The answers are vague. You bump the LLM from GPT-3.5 to GPT-4. The answers are still vague. You double the chunk size. Still vague. You spend three hours tuning prompts. Still. Vague.

The real problem isn't the model. It's that your pipeline is retrieving 10 chunks and the LLM is only seeing 3 of them — and nothing in your logs tells you that.

What's Actually Breaking (and Why You Can't See It)

A RAG pipeline has at least two moving parts between a user query and an answer: a retrieval step that fetches relevant chunks from a vector store, and an LLM call that uses those chunks to generate a response.

The failure mode that kills most RAG quality work is invisible: chunks are retrieved, then silently discarded before they reach the LLM prompt.

This happens because of TOP_K. You set TOP_K=10 thinking more context is better. But your LLM has a token budget. The orchestration layer (LangChain, LlamaIndex, your custom code) fills the prompt until it hits the limit — and quietly drops whatever didn't fit. The LLM never saw chunks 4 through 10. Your logs show a successful retrieval. Your logs show a successful LLM call. Nothing reports that 70% of your retrieved context was thrown away.

There are three failure patterns that account for most bad RAG answers:

TOP_K too high. You retrieve 10 chunks, the LLM uses 3. The 7 you paid to embed, store, and retrieve contribute nothing. Worse: if the 3 that fit aren't the 3 most relevant, your answer quality is determined by which chunks happened to survive token truncation rather than which ones actually matched the query.

Near-duplicate chunks. Sliding-window chunking creates overlapping segments. If chunk 3 ends with "...chlorophyll to capture light and convert it into chemical energy" and chunk 4 starts with the same phrase, you've burned 30% of your context window repeating one sentence. The model sees it twice and may over-weight it.

Missing similarity scores. Some vector stores (notably Chroma with L2 distance) return raw distance values, not normalized [0, 1] similarity scores. Your retrieval logs show scores like 1.42 and 0.93 with no indication which is better. Without normalized scores you can't tune thresholds or understand ranking.

These are all measurable. You just need something to measure them.

One Command to Add a Quality Gate

npx ragscope start

That starts a local OTLP receiver on port 4321. Then point your pipeline at it with one environment variable:

OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4321

If you're using Traceloop or OpenLLMetry for instrumentation, that's all you need — they auto-instrument LangChain, LlamaIndex, OpenAI, Qdrant, and Cohere out of the box:

import { Traceloop } from '@traceloop/node-server-sdk';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';

Traceloop.init({
  exporter: new OTLPTraceExporter({ url: 'http://localhost:4321/v1/traces' }),
});

For Vercel AI SDK or custom pipelines, add two span attributes: one on the retrieval span listing your chunks, and one on the LLM span with the full prompt text. That's the minimum RAGScope needs to score a trace.

Run your app, fire a few queries, and your terminal shows this:

  PASS  90/100  █████████░  my-rag-app
  │  "What is RAG?"
  │
  │  ✓  precision    90  █████████░  9/10 chunks used
  │  ✓  efficiency   80  ████████░░  20% tokens wasted
  │  ✓  uniqueness  100  ██████████  chunks are distinct
  │  ✓  coverage    100  ██████████  all chunks scored
  │

  WARN  54/100  █████░░░░░  my-rag-app
  │  "What is dense passage retrieval?"
  │
  │  ✗  precision    40  ████░░░░░░  4/10 chunks used
  │  ~  efficiency   50  █████░░░░░  50% tokens wasted
  │  ~  uniqueness   65  ███████░░░  2 near-duplicate pairs
  │  ✓  coverage    100  ██████████  all chunks scored
  │
  │  → Reduce TOP_K 10→4 (only 4 chunks reached LLM)
  │  → 50% of retrieved tokens never reached the LLM
  │  → 2 near-duplicate chunks — deduplicate at ingest time
  │

  ──────────────────────────────────────────────────
  Session  2 queries  ·  avg 72/100  ↓

Every trace is scored the moment it arrives. No dashboard to open, no query to run — just a PASS/WARN/FAIL with specific numbers sitting next to the query that produced them.

Reading the Score — What Each Number Means

Four sub-scores combine into a single 0–100 overall score. The weights reflect actual impact on answer quality.

Precision (40%) — what fraction of retrieved chunks appeared in the LLM prompt. This is weighted highest because a chunk that doesn't reach the LLM has zero value to the answer. It consumed retrieval latency, vector bandwidth, and context window space, and then got dropped. A score of 40 means Reduce TOP_K 10→4 (only 4 chunks reached LLM) — RAGScope tells you the exact number to set it to.

Efficiency (30%) — what fraction of retrieved tokens the LLM actually consumed. Low precision and low efficiency usually appear together, but they can diverge: if you retrieve three large chunks and the LLM fits two and a half, efficiency is low even though precision is decent.

Uniqueness (20%) — how distinct your chunks are from each other. Computed from exact text overlap between adjacent chunks (sorted by retrieval rank). Score of 100 means all chunks are fully distinct. A score of 65 with 2 near-duplicate pairs means your chunking strategy is creating redundant segments — deduplicate at ingest time or increase your chunk step size.

Coverage (10%) — whether your chunks carry non-zero similarity scores. This is a signal flag: if it fires, your vector store is returning raw values that couldn't be normalized, which means you also can't tune retrieval thresholds. RAGScope normalizes Chroma distances automatically, so this usually only fires when scores are genuinely missing from the trace.

The overall label maps to:

Score	Label	Meaning
≥ 75	PASS	Retrieval is healthy for this query
50–74	WARN	Issues present — review the recommendations
< 50	FAIL	Significant retrieval problems

Each WARN or FAIL comes with a concrete recommendation. Not "consider reducing TOP_K" — Reduce TOP_K 10→4 (only 4 chunks reached LLM). The actual number, derived from your actual trace.

Conclusion

Adding a quality gate to your RAG pipeline takes one command and one environment variable. From that point, every query you run during development is scored — precision, efficiency, uniqueness, coverage — with specific recommendations when something is wrong.

You stop guessing whether a model upgrade or a prompt rewrite will fix the vague answers. You see whether the retrieval pipeline is the problem, and exactly where it's breaking.

RAGScope runs entirely locally. No accounts, no configuration files, no data leaving your machine. Trace data lives in memory for the session lifetime. It's the same category of tool as a linter: runs while you build, catches problems before users see them.

Try it on your next RAG session: GitHub · npm

Key Takeaways

Most RAG quality problems are retrieval mechanics problems, not model problems — and they're invisible without tracing
TOP_K too high is the most common culprit: chunks are retrieved, then silently dropped before the LLM prompt is assembled
npx ragscope start + one env var adds a live PASS/WARN/FAIL score to every query during development
Precision (40% weight) measures chunk utilization; efficiency (30%) measures token utilization — both usually fix with TOP_K reduction
Near-duplicate chunks from sliding-window chunking waste context window space and can bias model outputs

Three Commands to Make Claude Code Stop Guessing Your Infra

Siddharth Pandey — Fri, 05 Jun 2026 18:30:45 +0000

You asked Claude Code to add a query for orders by customer status. It generated a .scan() with a FilterExpression. Your Orders table has 50M rows and three functions already hammering the same partition key. Claude Code had no idea — it read your TypeScript files, not your AWS account.

That's the problem. AI coding assistants are literate in your source code. They are blind to your infrastructure.

GitHub · npm

What Claude Code Actually Sees (and What It Doesn't)

When Claude Code reads your codebase, it builds a model of your application: function names, variable patterns, the string "Orders" passed to DynamoDB.DocumentClient. It can follow call chains, infer intent, and generate syntactically correct code.

What it cannot do is describe your actual infrastructure:

It doesn't know which GSIs exist on your DynamoDB tables
It doesn't know how your tables are partitioned or what sort keys you use
It doesn't know that listAllOrders() already does a full scan and costs $40/day
It doesn't know that 5 functions already write to the same partition key on Sessions

So when you ask it to add a new query, it generates something that looks correct. It might use .query() instead of .scan(). But it'll query on an attribute with no index — because it has no way to know which attributes are indexed. It'll write a FilterExpression that reads every item before filtering — which is exactly a scan, just spelled differently.

The code compiles. Tests pass. The problem ships.

The Three Commands That Close the Gap

infrawise gives Claude Code deterministic knowledge of your infrastructure through the Model Context Protocol. Three commands get you there.

1. infrawise init

cd your-project
infrawise init

Runs once per project. Detects your AWS profile and region, asks which databases you use, and writes a single file: infrawise.yaml. That's the only file it creates in your repository — one config, no framework, no SDK changes.

2. infrawise doctor

infrawise doctor

Before you trust any analysis, verify that infrawise can actually reach your infrastructure. Doctor checks every configured adapter — DynamoDB, PostgreSQL, Lambda, S3 — and reports what's reachable.

This step matters more than it sounds. If your AWS credentials are stale or your DB password rotated, infrawise analyze will run against cached metadata from last week and give you confident-but-wrong context. Doctor catches this before you feed stale data to Claude Code.

✓ DynamoDB  Connected (profile: default)
✓ PostgreSQL  Connected
✗ Lambda  credentials expired

Fix what's broken, then move on.

3. infrawise dev

infrawise dev

The command you run while you work. It runs a fresh analysis of your repository and infrastructure, then starts an MCP server that Claude Code queries during code generation.

If no analysis cache exists, it runs one automatically. If your infrastructure changes — you add a GSI, a new Lambda, a new table — run infrawise dev again and the context updates.

claude mcp add --transport http infrawise http://localhost:3000/mcp

From that point, every time Claude Code generates infrastructure-touching code, it queries this server first.

What Claude Code Can See After You Run Them

Here's what infrawise analyze surfaces on a real project:

Findings  3 total

1.  HIGH  Full table scan detected on DynamoDB table "Orders"
         listAllOrders() scans without any filter — reads every item in the table.
       → Replace Scan with Query using a partition key or add a GSI.

2.  MED   PostgreSQL table "users" has no index on column "email"
         Filtering on "email" causes sequential scans.
       → CREATE INDEX CONCURRENTLY idx_users_email ON users(email);

3.  MED   DynamoDB table "Sessions" accessed by 6 distinct code paths
         High access concentration may create hot partition issues at scale.
       → Consider write sharding or DynamoDB DAX for read-heavy workloads.

These aren't generic warnings. They name the function (listAllOrders), the table (Orders), and the exact fix (CREATE INDEX CONCURRENTLY idx_users_email ON users(email)). The GSI recommendation for DynamoDB includes the exact config — attribute name, key type, projection — not a suggestion to "consider adding an index."

When Claude Code queries the MCP server and gets this context:

It won't suggest .scan() on Orders — it knows the table has 50M rows and an existing high-severity finding
It will use the correct partition key and GSI name when building a .query() — because it knows both
It won't recommend adding a GSI on status — because it knows that GSI already exists
It will note that Sessions already has 6 access paths before adding a seventh

You're not getting a smarter model. You're giving the existing model the facts it was missing.

Conclusion

The gap between AI-generated code and production-safe code is mostly an information gap. Claude Code is capable of writing correct infrastructure queries — it just doesn't have your infrastructure. infrawise init connects it. infrawise doctor validates the connection. infrawise dev keeps it current.

Three commands. One config file. No changes to your application code.

Key Takeaways

Claude Code reads code, not cloud — that's the gap infrawise fills
infrawise init runs once and writes a single infrawise.yaml to your project
infrawise doctor prevents you from trusting analysis built on stale or broken connections
infrawise dev keeps infra context fresh automatically and serves it over MCP
Findings are specific: function name, table name, exact SQL or GSI config — not generic advice

Stop AI From Recommending Redundant Indexes on Existing GSIs

Siddharth Pandey — Wed, 03 Jun 2026 17:15:28 +0000

Hook — The GSI Your AI Doesn't Know About

You asked Claude Code to fix a slow query on your Orders table. It came back with a recommendation: add a GSI on customerId — index name Orders-customerId-index, projection type ALL. Clean, well-formatted, ready to paste into Terraform.

Your Orders table already has Orders-customerId-index. Has had it for eight months.

The AI read your code. It saw a .query() call filtering on customerId, noticed you weren't explicitly referencing an index name, and concluded one was missing. It never checked your actual DynamoDB table. It couldn't — it had no way to.

infrawise fixes this by reading your real infrastructure first, before any code gets written.

Why AI Gets GSIs Wrong Every Time

AI coding assistants are good at reading code. They're not reading your AWS account.

When Claude Code or Copilot sees this:

const result = await docClient.query({
  TableName: 'Orders',
  KeyConditionExpression: 'customerId = :cid',
  ExpressionAttributeValues: { ':cid': customerId },
});

It has two choices: assume you're using the table's partition key, or flag a potential missing index. Without explicit index name in the code, a cautious AI will suggest one. It's the right instinct — but the wrong answer, because the index already exists.

The damage isn't just a wasted suggestion. It's the next step: a junior engineer applies the Terraform diff, CloudFormation complains about a duplicate index name, and now you've got an incident ticket. Or worse — the AI generates a second index with a slightly different name (Orders-customerId-gsi), and now you're paying for duplicate write capacity on every Orders write.

How infrawise Reads Your Actual GSI Definitions

When you run infrawise analyze, the DynamoDB adapter calls DescribeTable on every table in your account. The response includes GlobalSecondaryIndexes — the full list of indexes that actually exist, right now, in production:

GET /  →  DescribeTable { TableName: 'Orders' }

Response:
  GlobalSecondaryIndexes:
    - IndexName: Orders-customerId-index
      KeySchema: [{ AttributeName: customerId, KeyType: HASH }]
      Projection: { ProjectionType: ALL }
    - IndexName: Orders-status-date-index
      KeySchema: [{ AttributeName: status, KeyType: HASH }, { AttributeName: createdAt, KeyType: RANGE }]

These index names go directly into the graph as uses_index edges on the table node. The graph now knows: Orders has two GSIs, covering customerId and the status + createdAt composite pattern.

The MissingGSIAnalyzer checks for tables with query edges but zero uses_index edges — tables your code queries that genuinely have no indexes at all. If Orders has uses_index edges, the analyzer doesn't fire for it. No false alarm, no redundant suggestion.

What the MCP Tools Surface Before You Write Anything

Once infrawise dev is running, Claude Code connects to it and the workflow changes. Before writing any query logic, the first call is get_infra_overview:

→ get_infra_overview

Tables:
  Orders          dynamodb
  Products        dynamodb
  UserSessions    dynamodb

High-severity findings: 0
Medium-severity findings: 1
  → UserSessions has no GSIs but is queried by 3 functions

Orders is there. No finding next to it — because it has indexes. The AI sees this and knows not to suggest new ones.

If you then call analyze_function on the function that queries Orders, the response includes the existing uses_index edges:

→ analyze_function { function: "getOrdersByCustomer" }

Services accessed:
  Orders  (query, uses_index: Orders-customerId-index)

Findings: none

The index name is right there. The AI writes the query with IndexName: 'Orders-customerId-index' — not because it's smart, but because it's reading real data.

The suggest_gsi tool is explicit about its own limitation. Its description reads: "Does not verify whether the GSI already exists; check the table schema in get_infra_overview first." It's intentionally a generation tool, not a verification tool. Verification is get_infra_overview. The workflow is: look first, generate only if it's missing.

Conclusion

The problem isn't that AI is careless. It's that AI is working from code, and code doesn't contain your infrastructure state. A .query() call doesn't tell you whether the table has an index. A function name doesn't tell you what's deployed.

infrawise bridges that gap by pulling live infrastructure state — DescribeTable, real index names, real projection types — and exposing it through MCP before any code gets written. The AI stops suggesting indexes that exist because it can now see the ones that do.

npm install -g infrawise, run infrawise init in your repo, then infrawise dev. The first time Claude Code calls get_infra_overview and sees your actual table schema, the redundant GSI suggestions stop.

GitHub · npm

Key Takeaways

AI suggests GSIs based on query patterns in code — it has no visibility into indexes that already exist in your AWS account
infrawise calls DescribeTable on every DynamoDB table and extracts the full GlobalSecondaryIndexes list into the infrastructure graph
MissingGSIAnalyzer fires only on tables with zero GSI coverage — tables that already have indexes don't trigger it
get_infra_overview surfaces existing index names before any code is written; analyze_function shows which index a specific query uses
suggest_gsi is a generation tool — call it only after get_infra_overview confirms the index doesn't exist

How infrawise Catches the DynamoDB Scan You Didn't Know You Were Making

Siddharth Pandey — Mon, 01 Jun 2026 15:12:25 +0000

Your Orders table has 50 million rows. Claude Code wrote a listAllOrders() function that calls .scan() with no filter. It compiled. Tests passed. Friday morning, your DynamoDB bill had a new line item.

The problem isn't the AI — it's that the AI had no way to know. infrawise solves this by building a deterministic model of your actual infrastructure and exposing it through MCP before any code gets written. This post is about how the scan detection actually works under the hood.

Step 1: Scanning the Repository with ts-morph

When you run infrawise analyze, the first pass is a TypeScript/JavaScript AST scan using ts-morph. infrawise walks every source file looking for database client call expressions — DynamoDB DocumentClient.scan, .query, .get; PostgreSQL pg.query; Mongoose model methods.

For each call site it finds, it records three things: the containing function name, the target table or collection, and the operation type. A .scan() call becomes an edge with type scan. A .query() call becomes a query edge. These edges are the raw material for the graph.

The limitation is real and documented: only TypeScript and JavaScript are supported. Dynamically constructed queries — where the table name or operation is assembled at runtime from a variable — may not resolve. infrawise handles what static analysis can handle and flags the rest.

Step 2: Infrastructure Introspection

In parallel, infrawise calls your AWS APIs directly. For DynamoDB it reads every table's actual schema: partition key, sort key, every GSI with its projection type and key schema, item count, billing mode. For Lambda it reads function configurations, memory, timeouts, and event source mappings. SQS queues, SNS topics, SSM parameters, Secrets Manager secrets, RDS instances, and CloudWatch log groups are all pulled the same way — deterministic API calls, no inference.

This is what separates it from passing your Terraform files to an AI. Reading a .tf file tells you what should exist. Calling dynamodb.describeTable tells you what does exist, right now.

Step 3: Building the Graph

The graph engine connects the AST output to the infrastructure metadata. Each DynamoDB table, Lambda function, SQS queue, and RDS instance becomes a node. The call sites from the AST scan become typed edges between function nodes and table nodes: scan, query, get, publishes_to, uses_index.

The result is a queryable graph. You can ask: which function nodes have scan edges pointing to the Orders table node? That's exactly the query the FullTableScanAnalyzer runs.

Step 4: The 24 Analyzers

infrawise ships 24 rule-based analyzers. Each one is a graph traversal or a schema comparison — no model, no inference.

FullTableScanAnalyzer calls getScanEdges, which filters all graph edges where type === 'scan'. For each edge that points to a DynamoDB table node, it records the table and the calling function, then emits a HIGH severity finding. No threshold, no heuristic — any .scan() on a DynamoDB table is flagged:

  1.  HIGH   Full table scan detected on DynamoDB table "Orders"
             The table "Orders" is being scanned without any filter,
             which reads every item. This is expensive and slow for
             large tables. Called from: listAllOrders
             → Replace Scan with a Query operation using a partition
               key or GSI. If filtering is required on non-key
               attributes, add a Global Secondary Index (GSI).

The other analyzers follow the same pattern. MissingGSIAnalyzer finds tables that have query edges but no uses_index edges — tables being queried with no GSI coverage. HotPartitionAnalyzer counts distinct function nodes with edges to the same table; at five or more, it fires MEDIUM. MissingIndexAnalyzer compares PostgreSQL query predicates against the introspected pg_indexes view. NplusOneAnalyzer looks for repeated query edges from the same function in a loop pattern. Every rule is structural.

How This Reaches Your AI Assistant

Running infrawise dev starts a Fastify MCP server on Streamable HTTP. Claude Code connects to it and can query 13 tools — get_infra_overview, analyze_function, suggest_gsi, postgres_index_suggestions, and others.

When Claude Code is about to write a query against Orders, it calls analyze_function first. The response includes the table schema, any existing GSIs, and the scan finding if one was detected. The AI writes a query with the correct partition key instead of a scan — not because it's smarter, but because it now has the same information a senior engineer would check before touching the table.

For Claude Desktop, infrawise stdio starts the same server on stdio transport.

Conclusion

The scan finding is the most visible output, but the real work is the graph: AST edges from ts-morph connecting function call sites to infrastructure nodes from live AWS APIs, traversed by 24 deterministic rules. No LLM touches the analysis path.

If you're running Claude Code against a codebase with DynamoDB tables, npm install -g infrawise and infrawise init in your repo. The first infrawise analyze usually finds something your AI assistant would have gotten wrong.

GitHub · npm

Key Takeaways

infrawise uses ts-morph to parse TypeScript/JavaScript source into a graph of function-to-table edges, typed by operation (scan, query, get).
AWS infrastructure metadata comes from live API calls — not Terraform, not static files — so the graph reflects what actually exists.
24 rule-based analyzers traverse the graph deterministically; FullTableScanAnalyzer flags any .scan() edge to a DynamoDB table as HIGH with no threshold.
Context is exposed through an MCP server (Streamable HTTP for Claude Code, stdio for Claude Desktop) so AI tools see findings before they generate code.
The analysis path contains zero LLMs — every finding is a graph query or schema comparison.

Git Knows Who. AI Knows What. Nobody Knows Why.

Siddharth Pandey — Sun, 31 May 2026 11:24:18 +0000

Modern software development has achieved incredible things.

AI can generate entire features.

Editors can autocomplete your thoughts before you've finished having them.

Agents can open PRs while you're still reading the ticket.

And yet, despite all this progress, there is still one question capable of ruining a senior engineer's afternoon:

Why the hell does this code exist?

Consider this innocent little gem:

if (distance < 50) {
  return;
}

Looks simple.

AI can explain it.

Git can tell you who wrote it.

The PR can tell you when it was merged.

But nobody can tell you why it was added in the first place.

Was it reducing GPS noise?

Was it preventing duplicate events?

Was it added because thousands of devices were rapidly entering and exiting the same geofence?

Was it a workaround for a production incident that woke up three engineers on a Sunday morning?

We may never know.

The Archaeology Phase of Software Engineering

Every mature codebase eventually turns developers into archaeologists.

You discover a mysterious piece of code and begin the sacred ritual:

Check Git blame.
Open commit.
Open PR.
Open linked ticket.
Ticket references a Slack discussion.
Slack link is dead.
Original author left the company.
Team lead moved to another startup.
Nobody remembers anything.

Congratulations.

You have reached the end of the knowledge graph.

The only remaining documentation is a comment that says:

// Don't remove this

Thank you, mysterious engineer from 2023.

Very helpful.

AI Is About To Make This Much Worse

The old workflow looked like this:

Human thinks
    ↓
Human writes code
    ↓
Human forgets why

The new workflow looks like this:

Human writes ticket
    ↓
AI writes code
    ↓
Human edits code
    ↓
Another AI refactors code
    ↓
Reviewer requests changes
    ↓
Code reaches production
    ↓
Everyone forgets why

We have successfully automated everything except remembering our decisions.

We Have Documentation Everywhere

The funny thing is that companies already have mountains of documentation.

The requirement is in Linear.

The discussion is in Slack.

The design is in Notion.

The implementation is in GitHub.

The AI conversation is in Cursor.

The meeting notes are somewhere in a folder named:

Final_v2_Updated_Final_Real_Final

The problem isn't missing information.

The problem is that all the information lives in different universes.

Git Answers The Wrong Question

Git is fantastic.

Ask Git:

Who changed this?

Git:

Bob.

Ask Git:

When?

Git:

February 14th, 2026.

Ask Git:

Why?

Git:

Commit message: "fix stuff"

Fantastic.

Outstanding.

Truly the pinnacle of human knowledge preservation.

The Shortcut We Actually Need

We already have:

Go To Definition
Find References
Rename Symbol

What we don't have is:

Ctrl + Y

Which means:

Why is this here?

Imagine clicking a line of code and seeing:

Reason:
Ignore GPS drift within 50 meters.

Requirement:
TRACKING-123

Discussion:
Customers reported phantom arrivals and departures.

Implementation:
PR #482

Generated by:
Cursor

Reviewer:
Sarah

Business Assumption:
Location updates within 50 meters are considered noise.

Now that's useful.

Because most bugs aren't caused by developers not understanding code.

They're caused by developers not understanding decisions.

The Missing Layer

For decades we've been obsessed with source code.

Then we became obsessed with documentation.

Now we're obsessed with AI code generation.

Meanwhile the most valuable thing keeps disappearing:

The reasoning.

The chain actually looks like this:

Requirement
    ↓
Discussion
    ↓
Decision
    ↓
AI Generation
    ↓
Code Review
    ↓
  Code

Today we only preserve the last two steps.

Then six months later we hold a meeting to rediscover the first four.

Maybe This Is the Next Developer Tool

What if a VS Code extension could answer:

Why does this code exist?

Not by hallucinating.

Not by guessing.

But by building a traceable chain:

Requirement
    ↓
Discussion
    ↓
AI Session
    ↓
Code Review
    ↓
  Code

Click a line.

Press Ctrl+Y.

Get the story.

Not just the syntax.

Future Technical Debt

People think AI-generated code is the next challenge.

I disagree.

The next challenge is AI-generated code with missing context.

Code can be read.

Logic can be reverse-engineered.

Intent is much harder.

And every year we're generating more code while preserving less reasoning.

That's a dangerous trade.

Final Thought

Git knows who.

AI knows what.

Nobody knows why.

And somewhere inside your production codebase is a line that nobody dares delete because the original author left three companies ago and the only documentation says:

// Trust me

Which, historically, has never caused any problems.

How RAGScope Knows Which Chunks Your LLM Actually Used

Siddharth Pandey — Sun, 31 May 2026 09:46:24 +0000

Your retriever fetched 10 chunks. Your LLM only used 3. RAGScope shows a precision score of 30 out of 100. The question every new user asks: how does it know?

There is no OpenTelemetry attribute that says "this chunk was in the context window." RAGScope infers it — and the way it does this is the most consequential piece of engineering in the whole tool.

There Is No "In Context" Attribute in OTel

The OpenTelemetry semantic conventions for generative AI (gen_ai.*) define attributes for model, input/output tokens, and retrieved documents. They do not define anything like gen_ai.chunk.reached_llm or gen_ai.retrieval.used_document_ids.

When your RETRIEVER span fires, you get a list of documents. When your LLM span fires, you get a prompt and a completion. The two spans are connected by a parent-child trace relationship — but there is no attribute that maps which retrieved documents appear in which prompt.

This gap matters. A reranker might drop 7 of your 10 chunks. Your application code might apply a token budget and truncate 4 more. From the trace alone, you cannot tell.

RAGScope needs this information to compute the precision sub-score — the highest-weighted metric at 40% of the overall score. Getting it wrong would make precision meaningless.

The Substring Match — How `assembleContext` Works

RAGScope's answer is in src/enrichment/pipeline.ts, in a function called assembleContext:

function assembleContext(chunks: RagChunk[], llmSpans: ParsedSpan[]): RagChunk[] {
  const llmPrompts = llmSpans.map((s) => s.prompt).filter((p): p is string => !!p);
  if (llmPrompts.length === 0) return chunks;

  let position = 0;
  return chunks.map((chunk) => {
    if (!chunk.content) return chunk;
    const inContext = llmPrompts.some((p) => p.includes(chunk.content!));
    if (inContext) {
      return { ...chunk, inContext: true, contextPosition: position++ };
    }
    return { ...chunk, inContext: false, contextPosition: null };
  });
}

The approach: collect the raw prompt strings from every LLM span in the trace, then check whether each chunk's content appears as a literal substring of any of those prompts.

If your LLM span records its prompt in the input attribute — which TraceAI, Traceloop, and OpenTelemetry's gen_ai conventions all do — and your retriever span records the chunk content in gen_ai.retrieval.documents — RAGScope has everything it needs.

The contextPosition counter assigns an incrementing index to each in-context chunk in the order they are encountered during the chunks.map() iteration — which follows retrieval rank, not prompt position. It tracks which retrieved chunks are in context and their relative order among in-context chunks.

Why substring matching works

Frameworks like LangChain and LlamaIndex build LLM prompts by concatenating retrieved chunk contents, often wrapped in minimal formatting like Context:\n{chunk}\n. The chunk text itself is usually present verbatim. As long as the chunk content recorded on the RETRIEVER span matches what was injected into the prompt string — which it does when both come from the same retrieval call — substring matching is reliable.

The constraint: chunk.content must be non-empty and non-null. RAGScope only stores content when the RETRIEVER span includes it in the documents array. If your instrumentation omits content and only records chunk IDs, assembleContext cannot match, and precision will read 0% until content is included.

What This Means for Your Precision Score

scoreRetrieval in src/audit/scorer.ts uses the inContext flag directly:

function scoreRetrieval(chunks: RagChunk[]): SubScore {
  const used = chunks.filter((c) => c.inContext).length;
  const score = Math.round((used / chunks.length) * 100);
  return {
    name: 'precision',
    score,
    symbol: symbol(score),
    finding: `${used}/${chunks.length} chunks used`,
    recommendation:
      score < 60
        ? `Reduce TOP_K ${chunks.length}→${Math.max(used, 3)} (only ${used} chunks reached LLM)`
        : null,
  };
}

If 3 of 10 chunks appear in the LLM prompt, precision = 30. The recommendation fires automatically: Reduce TOP_K 10→3. The score contributes 40% to the overall — a 30 on precision alone floors your overall score to at most 43, even if efficiency, redundancy, and coverage are perfect.

This is the most common cause of FAIL scores: teams set TOP_K=10 during early experimentation and never reduce it. Ten chunks get retrieved. Three reach the LLM. The other seven waste token budget and push the efficiency score down too.

The --verbose flag makes this explicit. Each sub-score prints with its finding:

   ✗  precision    30/100  3/10 chunks used
   ✗  efficiency   45/100  55% tokens wasted

And the Recommendations section:

 Recommendations
   → Reduce TOP_K 10→3 (only 3 chunks reached LLM)
   → 55% of retrieved tokens never reached the LLM

When precision reads 0% unexpectedly

If your trace has no LLM spans — for example, you're testing your retriever in isolation — llmPrompts will be empty and assembleContext returns all chunks unchanged with inContext: false. In that case, scoreRetrieval sees zero used chunks over a non-zero total, and precision reads 0.

If your trace has no chunks at all, scoreRetrieval short-circuits to a score of 100 with the finding no chunks — the assumption being that a trace with no retrieved chunks represents a non-retrieval query that shouldn't be penalized.

Conclusion

RAGScope's precision score is only meaningful because assembleContext solves the hardest observability problem in RAG pipelines: figuring out which retrieved chunks actually reached the model. It does this by checking chunk content against LLM prompt strings — no extra instrumentation, no special attributes, no embeddings.

The implication for your setup: include chunk content in your RETRIEVER spans. Without it, assembleContext cannot match, precision stays at zero, and the most impactful metric in your audit is blind. With it, you get the exact number that tells you whether your TOP_K setting is costing you context budget.

Try it: GitHub · npm

Key Takeaways

OTel has no "in context" attribute — RAGScope determines LLM context inclusion by checking if chunk content is a substring of the LLM span's prompt string
assembleContext in src/enrichment/pipeline.ts performs this matching; contextPosition tracks relative order among in-context chunks (by retrieval rank, not prompt position)
Precision is 40% of the overall score — a low precision score is the most common cause of FAIL labels
If chunk content is missing from your RETRIEVER spans, precision will read 0%; include content in your instrumentation to get accurate scores
The automatic recommendation (Reduce TOP_K N→M) fires when precision < 60%, giving a concrete action to take immediately

DEV Community: Siddharth Pandey

Your DB Is Still Red After Adding a Cache — Here's Why

Hit Rate Isn't a Setting

The Comparative in Action

When Write Policy Matters

Conclusion

Key Takeaways

Why Your Reranker Isn't Helping Your RAG Pipeline (And How to Prove It)

What "Reranker Gain" Actually Measures

Reading the Signal — What Good and Bad Look Like

What to Do When the Reranker Is Hurting

Conclusion

Key Takeaways

Fix N+1 Trigger Patterns Where Lambda Functions Hammer the Same DynamoDB Partition Key

Why the LLM Can't See the Pattern

How Infrawise Traces Trigger Chains to the Same Table

Fixing It — Restructuring the Key or Sharding the Access Pattern

Conclusion

Key Takeaways

Stop Paying For Retrieval Latency On Chunks You Never Use In The Prompt

Your pipeline fetched 10 chunks. Your LLM saw 3.

Where the Chunks Disappear

How ragscope Measures precision

Tuning TOP_K Based on the Audit

The Number You Should Check First

Key Takeaways

Why Infrawise Uses Deterministic Analysis Instead of an LLM

Infrastructure questions are lookups, not generation

What deterministic extraction looks like

Rules, not vibes

The LLM is the consumer, not the analyst

Key takeaways

Give Your AI Assistant Infrastructure Eyes Before It Writes Another Query

What AI Assistants Don't Know About Your Infrastructure

What Happens When infrawise Is in the Loop

Wiring It Up — infrawise start --claude

Conclusion

Key Takeaways

Add a PASS/WARN/FAIL Quality Gate to Your RAG Pipeline in 30 Seconds

What's Actually Breaking (and Why You Can't See It)

One Command to Add a Quality Gate

Reading the Score — What Each Number Means

Conclusion

Key Takeaways

Three Commands to Make Claude Code Stop Guessing Your Infra

What Claude Code Actually Sees (and What It Doesn't)

The Three Commands That Close the Gap

What Claude Code Can See After You Run Them

Conclusion

Stop AI From Recommending Redundant Indexes on Existing GSIs

Hook — The GSI Your AI Doesn't Know About

Why AI Gets GSIs Wrong Every Time

How infrawise Reads Your Actual GSI Definitions

What the MCP Tools Surface Before You Write Anything

Conclusion

Key Takeaways

How infrawise Catches the DynamoDB Scan You Didn't Know You Were Making

Step 1: Scanning the Repository with ts-morph

Step 2: Infrastructure Introspection

Step 3: Building the Graph

Step 4: The 24 Analyzers

How This Reaches Your AI Assistant

Conclusion

Key Takeaways

Git Knows Who. AI Knows What. Nobody Knows Why.

The Archaeology Phase of Software Engineering

AI Is About To Make This Much Worse

We Have Documentation Everywhere

Git Answers The Wrong Question

The Shortcut We Actually Need

The Missing Layer

Maybe This Is the Next Developer Tool

Future Technical Debt

Final Thought

How RAGScope Knows Which Chunks Your LLM Actually Used

There Is No "In Context" Attribute in OTel

The Substring Match — How assembleContext Works

Why substring matching works

What This Means for Your Precision Score

When precision reads 0% unexpectedly

How ragscope Measures `precision`

The Substring Match — How `assembleContext` Works