SkillPedia Skills Encyclopedia
中文 EN
Today's updates 2026-11-18 UTC

No new commits yet today

Open the update feed

Skills 2026-10-09 20:59 UTC

agent-plugins

Committed by praba2210. Update Category: Documentation Updates. Commit details: docs(dsql): add limits/error-code reference, fix wrong messages (#279). This update refines the documentation for easier onboarding.

praba2210 fbefb37 awslabs/agent-plugins

CommitRaw commit message

docs(dsql): add limits/error-code reference, fix wrong messages (#279)

* docs(dsql): add limits/error-code reference, fix wrong messages

troubleshooting.md covered only 40001 and 23503, and five of its
quoted error messages did not match what DSQL emits. One matches
nothing in the real text, so an agent looking it up finds nothing.

Adds a Limits and Error Codes section: 22 limits, 20 rejections and
10 cluster quotas, each with its SQLSTATE and exact message. 54000
covers 15 limit rows and 0A000 covers 13 rejections, so within the
section the message is the discriminator, not the code.

Four corrections change the advice:

- OC001 is 40001, already in the OCC retry loop. OC000 is the DML
  conflict. OC001 fires when a transaction's snapshot predates a
  catalog change, which includes GRANT and REVOKE as well as DDL,
  and whether or not the change is still in flight. A retry takes a
  fresh snapshot and clears a one-shot change; only a session that
  keeps changing the catalog needs serializing.
- "unable to accept connection" is a prefix shared by five
  conditions. Only the Signature expired hint means the token is
  stale, and regenerating cannot fix a skewed host clock. HINT is a
  separate protocol field, so the guidance names it per driver.
- An EOF at or after COMMIT leaves the commit outcome unknown, so a
  bare retry can double-write. Adds what to do when the outcome
  cannot be established at all.
- dsql_lint strips index sort order rather than preserving it, and
  the severity depends on the direction: DESC is a warning, ASC is
  neither an error nor a warning, so gating on either counter misses
  the rewrite. Gate on the diagnostic list instead.

Corrects key size to about 1,981 usable bytes, shared across all key
columns and with any secondary index, and the 24-index limit to
include the primary key, so a table with one accepts 23 secondary.
Both confirmed against a cluster: a 500-byte primary key leaves
1,455 bytes for a secondary index key, and totals hold near 1,955
whatever the split. Key size, temp space and view-definition size
all differ from the quotas page; each row now says so.

Secondary indexes also count against the 10 MiB transaction limit,
which is documented nowhere. Accounted size runs about 150 bytes per
row above raw, plus about 430 per secondary index entry, measured
linear across 0, 1, 2 and 4 indexes and predictive to within 1% from
200 to 2,900 rows. A 3,000-row batch on a four-index table loses
roughly 5 MiB before any payload counts.

The eval grader accepted "24 secondary indexes" and a fixture pinned
it as passing, so the suite graded the error this commit fixes as a
correct answer. It also failed correct answers laid out as a quoted
table, bullet list or bolded number, which is what an eval requiring
a documentation call tends to produce. The grader now matches the
number and the index noun in either order, accepts bare "per table"
and "can have" as bounds, and scopes the inclusive exemption to the
statement that triggered the veto so one correct sentence no longer
licenses a wrong claim elsewhere. Adds the excluding phrasings it
missed: not including, doesn't count, plural primary keys, a fronted
clause and an em dash. Six tests pin 20 phrasings.

Adds five evals for the sort-order, transaction-size, EOF-at-COMMIT,
catalog-change and key-size guidance, which had none.

Also drops DESC from two index examples that return 0A000 today. A
direction-free index serves a uniformly ordered ORDER BY by backward
scan when the keys are a leading prefix and the projection is
covered; mixed ordering adds a sort.

Bumps the plugin version to 1.10.0.

* fix(dsql): address review on limits and OC001 guidance

OC001 hits reads too, so drop the read-only exemption. The cause is a
stale per-session catalog cache, not a transaction snapshot; eval 26
now accepts the documented completed-before-start case.

Drop the 10 MiB formula. Per-entry cost depends on index key and PK
width, so point agents at the 54000 DETAIL instead.

Every index counts toward the 24, UNIQUE included. Key budget is
~1,981 bytes less ~7 per extra column, 1,474 with a 500-byte PK. Add
the 2,000-byte DDL-time key check.

Zero lint diagnostics is not acceptance; drop the fixed_sql compare.
The EOF rule now covers autocommit writes. Fix the capitalisation
note and trim SKILL.md to 299 lines.

Fix INDEXES_PER_TABLE misgrades in both directions and pin each
probe in tests.

* fix(dsql): tighten index-limit grader, link EOF rule

The INDEXES_PER_TABLE grader still misgraded close variants of the
review probes. "up to 24 hours" after an index noun passed as the
cap, and correct answers failed: one naming DSQL rather than the
table, the no-primary-key caveat on its own (its "no" read as a
negation), and "23 secondary plus the primary key, 24 in total".
Each now grades correctly; five new test strings cover them.

occ-retry-patterns.md now links to the confirm-or-stop rule in
troubleshooting.md instead of offering idempotency as an alternative
to confirming. development-guide.md trims the index limit to one
clause.

* fix(dsql): move index PK check from regex to LLM judge

The INDEXES_PER_TABLE regex tried to veto every phrasing that puts
the primary key outside the 24, and each probe round found another
that slipped through. It now checks only that the cap is stated, as
24 per table or 23 secondary, and keeps the guards against other
units ("24 hours", "24 columns") and upper-bound wording.

Whether the 24 counts the primary key moves to eval 28, an LLM-judge
eval: a PostgreSQL table with a PK, a UNIQUE constraint and 23 other
indexes needs 25 slots in DSQL and does not fit. Eval 3's expectation
returns to its original wording, the PK-inclusive alias is dropped,
and the veto tests go with the veto.

* docs(dsql): split limits into their own reference

troubleshooting.md loads on any error and had grown to 415 lines.
The Limits and Error Codes section moves to limits-and-error-codes.md
with its own SKILL.md row, loaded before sizing batches, keys or
indexes and on a 54000/0A000/54011 error. troubleshooting.md keeps a
pointer and drops to 223 lines.

OC001 is now explained once, in occ-retry-patterns.md; the
troubleshooting entry keeps the cause, marker table and fix. The
24-slot paragraph in index-conversion.md becomes a link. The SKILL.md
OCC and size bullets are shorter but keep the facts evals 24 and 26
showed agents miss without them.

Drops the measurement date, the view-size series and "observed
here". Also drops the 54001 row and the 214 MiB figure, which did
not reproduce on re-test.

* docs(dsql): require approval before recreating a churned table

The dropped-columns note sent agents to recreate the table, which ends
in an irreversible drop. Say it needs user approval, alongside the
link to the procedure that carries the full gate.

* docs(dsql): load the skill for limit questions, act on measured limits

For limit and error-code questions agents answered from the AWS docs
and never loaded the skill, so the measured limits never reached
them. The description now asks for the skill on those questions.

Where a measured limit contradicts the quotas page, such as key size,
the reference now says to size against the measured value and mention
the documented one, instead of re-verifying against the docs.

* docs(dsql): cut SKILL.md error bullets to pointers

The OCC and transaction-size bullets in Error Scenarios restated the
references. They now route to occ-retry-patterns.md and
limits-and-error-codes.md, keeping only "keep OC001 in the retry
loop" and "size is checked at COMMIT"; eval 24 dropped the
COMMIT fact without it.

Eval 26 expectation 2 required "not two statements overlapping in
time", which fails a correct answer: the prompt fails at COMMIT, and
OC001 surfaces at COMMIT when the change lands mid-transaction. It
now accepts a GRANT that finished before the transaction or one that
committed during it. The expected_output and README row match.

---------

Co-authored-by: Prabakaran Annadurai <prabaw@amazon.com>