@kensio/skills 1.13.1

package/skills/dynamodb-single-table/references/aws-guidance.md

@@ -0,0 +1,183 @@
+# Mechanics behind the modelling rules
+
+The numbers and patterns the [SKILL.md](../SKILL.md) rules rest on, collected from the DynamoDB
+developer guide. Read this when the question turns on cost, throughput or size. Fetch the linked
+pages when a decision rests on an exact figure, because quotas move.
+
+## Partitions and throughput
+
+A table is stored in partitions, each backed by SSD and replicated across Availability Zones. AWS
+manages them and never exposes them directly. More partitions appear when provisioned throughput
+rises past what the current ones serve, and when an existing partition fills.
+
+DynamoDB hashes the partition key to choose the partition. Items sharing a partition key value form
+an **item collection**, held together and sorted by sort key, which is what makes a range query over
+one collection cheap. Where the table carries no local secondary index, DynamoDB splits an item
+collection across as many partitions as it needs, and there is no ceiling on the number of distinct
+sort key values under one partition key.
+
+**Every partition serves 3,000 read units and 1,000 write units per second.** One read unit is one
+strongly consistent read of an item up to 4 KB, or two eventually consistent reads. One write unit
+is one write of an item up to 1 KB. Item size multiplies this. A 20 KB item costs 5 read units per
+consistent read, which puts the ceiling at 600 reads per second against that one item.
+
+Source
+[Partitions and data distribution](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.Partitions.html)
+and
+[Best practices for partition keys](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/bp-partition-key-design.html).
+
+## Choosing a partition key that spreads
+
+Throughput efficiency rises with the ratio of partition key values accessed to partition key values
+that exist. The AWS comparison:
+
+| Partition key value                                             | Uniformity |
+| --------------------------------------------------------------- | ---------- |
+| User id, in an application with many users                      | Good       |
+| Status code, where few codes exist                              | Bad        |
+| Creation date rounded to a day, hour or minute                  | Bad        |
+| Device id, where devices are accessed at similar intervals      | Good       |
+| Device id, where one device is far more popular than the others | Bad        |
+
+The date case is the one that catches people. Every item created today lands on one partition key
+value and therefore one physical partition.
+
+A table small enough to fit in a single partition, allowing for growth, and whose throughput stays
+inside one partition's limits, will not throttle whatever the key looks like.
+
+Source
+[Designing partition keys to distribute your workload](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/bp-partition-key-uniform-load.html).
+
+## Write sharding
+
+Where the natural key concentrates writes, widen the key space by appending a suffix.
+
+**Random suffix.** Append a random number in a fixed range, giving `2026-07-09.1` through
+`2026-07-09.200`. Writes spread evenly. Reading one item back becomes impossible without knowing
+which suffix it took, and reading the whole day means one `Query` per suffix followed by a merge.
+
+**Calculated suffix.** Derive the suffix from an attribute the reader already holds, such as the sum
+of the UTF-8 code points of an order id modulo 200 plus 1. Writes spread the same way, and a
+`GetItem` for a known order still works because the suffix is recomputable. Reading the whole day
+still costs one `Query` per suffix.
+
+A GSI can be sharded the same way to make selective queries parallel.
+
+Source
+[Using write sharding](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/bp-partition-key-sharding.html).
+
+## Sort key patterns
+
+**Hierarchy.** A composite sort key defines one-to-many relationships queryable at any level, using
+`begins_with`, `between`, `>` and `<`. The AWS example is
+`[country]#[region]#[state]#[county]#[city]#[neighborhood]`.
+
+**Version history.** Keep two copies of every item. One carries a `v0_` sort key prefix and holds
+the current version, and each revision is written under the next number up (`v1_`, `v2_` and so on)
+with its contents also copied over `v0_`. The current version is then a query on the `v0_` prefix,
+and the history is the rest of the partition.
+
+Source
+[Best practices for sort keys](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/bp-sort-keys.html).
+
+## Secondary indexes
+
+A table gets 20 global secondary indexes (default quota) and 5 local secondary indexes. AWS says
+global indexes are usually the more useful of the two.
+
+**Keep the number to a minimum.** An index that is seldom queried adds storage and I/O cost and buys
+no performance.
+
+**Choose projections deliberately.** A smaller index costs less and outperforms the base table by
+more. Project the attributes the queries actually return. `ALL` removes every fetch and in most
+cases doubles storage and write cost. Where an index entry is under 1 KB the projection is free up
+to that point, because writes round up.
+
+**Avoid fetches on the read path.** Querying an LSI for an attribute it does not project makes
+DynamoDB read the whole item from the table, adding latency and I/O. Attributes queried occasionally
+have a habit of becoming attributes queried always.
+
+**Watch LSI item collections.** An item collection covers the table items and every LSI item sharing
+a partition key, and it cannot exceed 10 GB. Writes fail once it does. Pass
+`ReturnItemCollectionMetrics` on writes and alarm before the limit. An LSI cannot be deleted after
+creation, which makes the decision to add one permanent.
+
+Source
+[General guidelines for secondary indexes](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/bp-indexes-general.html).
+
+## Large items
+
+The item size limit is 400 KB, and exceeding it fails the write with a `ValidationException`. Pass
+`ReturnConsumedCapacity` on writes and alarm on items approaching the limit.
+
+Three ways out, in the order worth trying:
+
+- **Vertical partitioning.** Break the item into several items under one partition key, ordered by
+  sort key. This is the single-table answer and keeps everything queryable.
+- **Compression.** GZIP or LZO into a `Binary` attribute. A compressed attribute cannot be filtered
+  or queried on.
+- **S3.** Store the payload as an object and the object key in the item, with the item's primary key
+  in the S3 object metadata pointing back. No transaction spans the two, so the application owns the
+  cleanup of orphaned objects.
+
+Source
+[Best practices for storing large items](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/bp-use-s3-too.html).
+
+## What a Scan actually costs
+
+A `Scan` reads the whole table or index and then discards what the filter rejects. It slows as the
+table grows.
+
+A single 1 MB page of 4 KB items costs 128 eventually consistent read units, or 256 strongly
+consistent. That arrives as one spike, and it lands on one partition, because the items a scan reads
+sit next to each other. Requests sharing that partition throttle.
+
+Where a scan is needed:
+
+- Set `Limit` to shrink the page, which spreads the cost and leaves gaps for other traffic.
+- Use parallel segments once the table passes about 20 GB, starting at roughly one segment per 2 GB,
+  and only where the provisioned read capacity is not already busy.
+- Retry throttled requests with exponential backoff.
+
+Source
+[Best practices for querying and scanning](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/bp-query-scan.html).
+
+## Adjacency lists and the materialized graph
+
+Top-level entities become partition keys, and each relationship becomes an item in the partition
+whose sort key is the id at the other end. Data duplication stays minimal and the forward query is a
+plain `Query`.
+
+The reverse direction comes from an **inverted index**, a global secondary index whose partition key
+is the table's sort key.
+
+The materialized graph pattern extends this. Edge items carry `Type` and `Target` attributes
+composed into a `TypeTarget` key, one overloaded GSI indexes a `Data` attribute holding dates,
+names, places and skills, and a second GSI on `TypeTarget` answers reverse lookups. Aggregations
+large enough to run hot (everyone born on one date, everyone with one skill) want sharding across
+logical partitions.
+
+Multi-hop traversal at millisecond latency is Amazon Neptune's job. AWS says so on the many-to-many
+page itself.
+
+Source
+[Best practices for many-to-many relationships](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/bp-adjacency-graphs.html).
+
+## AWS's own trade-off lists
+
+Worth reading in full at
+[Data modeling foundations](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/data-modeling-foundations.html),
+because they are the most honest account of the cost of single-table design.
+
+What AWS counts against single-table design. The learning curve is steep because the design runs
+opposite to relational instinct, whole-table settings (backup, encryption, table class) apply to
+every entity at once, streams carry every change whether or not a consumer wants it, GraphQL is
+harder to implement, and higher-level SDK mappers struggle with one response holding several
+classes.
+
+What AWS counts for it. Data locality, fewer read units and fewer round trips, one set of
+permissions and alarms, one key to rotate, capacity averaged across entities, and traffic that
+smooths as patterns aggregate.
+
+AWS's summary of when multiple tables are the right answer is short. Where the access patterns never
+query several entities together, multiple tables are good and sufficient.

package/skills/github-issue-drafting/SKILL.md

@@ -0,0 +1,260 @@
+---
+name: github-issue-drafting
+description: Draft a GitHub issue from a short note or a rough idea, grounding every claim about the code in the repository the issue will be filed against, splitting work that is really two issues, and filing it with `gh` once the user has approved the draft. Use when turning a to-do item, a Slack message, a code TODO, a failing test or a bug report into an issue, when asked to "write up an issue for" something, to "raise", "file" or "open an issue", when asked whether something should be one issue or several, and when tidying the titles, types or labels of issues that already exist.
+license: Apache-2.0
+metadata:
+  version: "1.13.1"
+---
+
+# GitHub issue drafting
+
+A short note ("fix the retry backoff", "SSM params", "the CLI hangs on empty input") carries enough
+for whoever wrote it and too little for anyone else, including the same person in six months. The
+job is an issue a reader can act on without asking what was meant, with every claim about the code
+checked against the code.
+
+## Process
+
+1. **Get the note.** Use the text passed in as the skill argument. Ask the user for it if none
+   arrived. A note can come from anywhere (a to-do app, a chat message, a `TODO` comment, a stack
+   trace, a support thread) and the source changes nothing about the drafting.
+
+2. **Work out which repository this belongs to, and how it files issues.** `gh repo view` names the
+   repository behind the working directory. Confirm with the user where the working directory is
+   ambiguous or where the issue belongs somewhere else. Then read how this project already works:
+
+   - `.github/ISSUE_TEMPLATE/` and `CONTRIBUTING.md`, if present. **A repository's own template wins
+     over the structure in this skill.** Fill in that template and follow its wording.
+   - `gh issue list --limit 10` and one or two full issues (`gh issue view <n>`) for the house
+     register, the section headings in use, and how long a typical issue runs.
+
+3. **Investigate before drafting.** See
+   [Ground the draft in the repository](#ground-the-draft-in-the-repository).
+
+4. **Decide whether it is one issue or several.** See
+   [One note is often more than one issue](#one-note-is-often-more-than-one-issue).
+
+5. **Draft it**, separating what step 3 confirmed from what remains an assumption.
+
+6. **Present the draft in chat as markdown, and stop.** Filing is the user's call. List any open
+   questions under the draft so they can be answered before anything is posted.
+
+7. **File it with `gh` only after the user has explicitly asked.** See
+   [Filing the issue](#filing-the-issue).
+
+## Ground the draft in the repository
+
+The failure mode that matters is invention. A feature called missing when it half exists,
+architecture nobody built, acceptance criteria assuming decisions nobody has made. A note is too
+short to carry that context. The repository has to supply it.
+
+Budget a handful of tool calls for this. A full audit is more than the draft needs.
+
+- **Locate the area.** Grep for the nouns and identifiers in the note. A `README`, an architecture
+  doc or the directory layout usually points at the right subtree in one step.
+- **Read the code that would change, and its tests.** Half-built is the common case, and it is the
+  case that embarrasses the issue.
+- **Read what the docs already promise.** A behaviour documented as supported and a behaviour
+  actually supported are different facts, and the gap between them is sometimes the issue.
+- **Check the history.** `git log --oneline -20` for work in flight, and
+  `git log --oneline --all --grep="<keyword>"` for work already done under another name.
+- **Search the tracker, including closed issues.** `gh issue list --state all --search "<keyword>"`.
+  A near duplicate is usually worth a comment on the existing issue. Say so and let the user pick.
+  Where `gh` is missing or unauthenticated, skip this quietly and never claim to have checked.
+
+Carry the unresolved parts forward. Anything step 3 failed to settle belongs in the draft as an
+explicit question or a stated assumption, and in chat as something for the user to answer.
+
+## One note is often more than one issue
+
+A note is written in one breath. The work it names frequently spans several pull requests, and filed
+whole it becomes one enormous branch that is hard to review and hard to stop halfway.
+
+So before drafting, look for a seam that yields **independently shippable** issues. Seams that
+usually work, roughly in build order:
+
+- **A usable surface first, whatever sits on top of it second.** The library function is useful on
+  its own. The CLI flag, the config key or the framework integration exposing it reads better as a
+  follow-up that links back.
+- **A piece blocked on something unbuilt.** Work waiting on another feature is its own issue, with
+  the dependency named, and not a caveat buried in this one.
+- **A distinct usage mode.** The same capability reached at runtime and at build time is two
+  features with two sets of tests.
+- **A bug fix and the hardening around it.** Ship the fix. File the class of problem separately.
+
+Three seams produce issues nobody can ship alone. One issue per function or endpoint, implementation
+split from its tests, and docs as their own issue. Docs belong with the behaviour they describe.
+
+Two or three issues is the usual answer where a split is warranted. Five is over-slicing, and a
+small self-contained note stays one issue. Where a split happens, say so in chat and present the set
+together, each one naming its dependency and using **Out of scope** to hand work to the others.
+
+## Drafting rules
+
+- **Keep it short, and shorter than feels right.** Roughly 200 to 350 words of prose plus at most
+  one example. Three or four sections at most, and no more than six acceptance criteria. Cut any
+  section that fails to help a reader understand, implement, test or evaluate the change.
+- **The design discussion in chat is not the issue.** Working a note through produces rejected
+  alternatives, trade-offs and cost estimates, and almost none of it belongs in the body. Record the
+  decision and one sentence of reason. Where the discussion settled something genuinely surprising,
+  one short paragraph earns its place.
+- **Never invent behaviour, architecture, supported APIs or acceptance criteria.** Where step 3 left
+  something unconfirmed, write it as a question or a stated assumption.
+- **Scrub anything private before it goes anywhere public.** Notes and stack traces carry customer
+  names, internal hostnames, internal ticket ids, paths with a username in them, tokens and API
+  keys. A public issue is publication. Redact by default and ask about anything borderline.
+- **Write to the problem, and to the observable behaviour that would fix it.** An issue is not a
+  pull request description, and a detailed implementation plan belongs in it only where step 3
+  turned up a constraint the implementer would otherwise miss.
+- **Prefer one concrete example** (a command, a config snippet, a failing assertion, the exact error
+  text) over a paragraph of description.
+- **A bug needs the version, the environment, the steps, the expected result and the actual
+  result.** Anything absent is a question for the user, and a bug report missing them wastes the
+  first reply.
+- **Leave the process fields alone.** No assignees, milestones, estimates, or wording implying that
+  the issue is approved or scheduled. Type and labels are set at filing time.
+- **When in doubt, cut.** Erring long is the more common failure. Somebody re-reading this in six
+  months needs the problem, the intended behaviour, and enough grounding to trust both.
+
+### Prose
+
+Load the `technical-prose-style` and `avoid-ai-writing` skills before drafting where they are
+installed, and run whatever check they ship over the body. Where neither is available, aim for one
+claim per sentence, present tense, no em dashes, no marketing adjectives, and one name kept for one
+thing.
+
+## Structure
+
+Use the repository's own issue template where it has one. Otherwise draw from the sections below,
+taking only those this particular note needs. Most issues use three or four. **Problem** and
+**Desired behaviour** are the two that nearly always earn their place. Reach for **Current
+behaviour** where what exists today would surprise a reader, and for **Implementation notes** only
+where step 3 turned up a real constraint.
+
+```markdown
+# Title
+
+## Problem
+
+The concrete limitation, missing capability or user need.
+
+## Current behaviour
+
+What happens today, grounded in what the repository actually shows. Omit where unknown.
+
+## Desired behaviour
+
+The observable behaviour that should exist once this is implemented.
+
+## Example
+
+A command, config, request or expected result. Include it only where it clarifies something.
+
+## Acceptance criteria
+
+Testable checklist items.
+
+## Out of scope
+
+Related work that should not be assumed to be included.
+
+## Implementation notes
+
+Grounded constraints from the investigation. Omit the section entirely where there are none.
+```
+
+For a bug, replace the middle three with **Steps to reproduce**, **Expected result**, **Actual
+result** and **Environment** (version, runtime, operating system, anything version-pinned that
+matters).
+
+## Titles people can find
+
+Issues get indexed, by GitHub's search and by search engines, and they surface far more readily than
+pull requests do. For a public repository the title and the opening paragraph are the whole search
+snippet, and they do nearly all the work of getting the issue in front of the person who has the
+problem.
+
+- **Write the words a user would type.** Internal shorthand and internal abbreviations describe the
+  problem to people who already know it. Spell them out.
+- **Keep the term that makes the project distinctive**, even while cutting shorthand around it. The
+  two look like the same edit and are opposites. An abbreviation nobody searches for should go. The
+  one accurate word separating this project from every other page about the same topic should stay,
+  because a title without it competes with the upstream documentation and loses.
+- **Front-load.** Search snippets truncate around 60 characters, so anything load-bearing goes
+  early.
+- **Generic verbs are weak alone.** "add", "support", "fix" are fine where the sentence wants them
+  anyway. They differentiate nothing on their own, and forcing one in is where a title starts
+  sounding written for a crawler.
+- **Keep it subtle.** An issue that reads as search filler makes a project look automated, and costs
+  more credibility than the traffic is worth. Aim for a title a developer would have written anyway,
+  which happens to use the words someone with this problem would search for.
+- **Be honest about the size of the prize.** On a small repository these titles win long-tail
+  queries. That makes the work worth doing and never worth distorting a title for.
+
+`SSR hydration bug in the DS button` becomes
+`Design system button loses its click handler after server-side rendering`. The second expands the
+shorthand nobody searches for, keeps the words that place the problem, and adds nothing that is
+untrue of the bug.
+
+On a private repository the audience is the team, and all of this reduces to one rule. Say what the
+problem is in plain words.
+
+## Filing the issue
+
+Only once the user has explicitly asked.
+
+Write the body to a file and pass it with `--body-file`, so quoting and backticks survive intact:
+
+```bash
+gh issue create --repo <owner>/<repo> --title "<title>" --body-file <path> --label <label>
+```
+
+**Do not hard-wrap the body.** This is the one formatting trap. GitHub renders issue and comment
+Markdown with the GFM hard-line-break extension, so every newline inside a paragraph becomes a
+`<br>`. A repository whose prose style wraps at 80 or 100 columns will produce visibly ragged output
+when that habit reaches an issue body. Write each paragraph and each list item as one long line.
+Blank lines between blocks still separate paragraphs, and code fences and list structure are
+unaffected.
+
+**Labels.** Read `gh label list` and pick from what exists. A label passed to `gh` that the
+repository lacks fails the whole command.
+
+**Type,** where the organisation has issue types configured. `--type` takes one of them (`Bug`,
+`Feature` and `Task` are the GitHub defaults). Its value is in-repo filtering and a readable issue
+list. Where the flag or the type is rejected, drop it and carry on.
+
+**Think before applying `good first issue` or `help wanted`.** GitHub surfaces both in its
+contributor-discovery UI, and third-party sites scrape them to list approachable open-source work.
+For a project actively recruiting contributors that is the point. For a solo maintainer it invites
+drive-by pull requests that cost more to review than they return. `CONTRIBUTING.md` and the existing
+issues usually say which kind of project this is. Where it stays unclear, leave both off and mention
+it.
+
+**Skip Projects and date fields** unless the user asks for them. They are planning tools with
+recurring upkeep and no search benefit. Milestones are the lighter option for grouping.
+
+Where several issues came out of one note, file them in dependency order and put each preceding URL
+into the issue that depends on it.
+
+After filing, report the URL and state plainly which type and labels were applied.
+
+## Revisiting existing issues
+
+The same thinking applies to issues that already exist, whether retitling or backfilling a missing
+type or label. Closed issues are worth including. They stay indexed, and a closed issue describing a
+capability that now exists is often exactly what a searcher wants.
+
+Retitling is cheap and low-risk (the URL survives, GitHub keeps the edit history, nobody gets
+notified) and it is still a public edit. Propose the full set in chat and get an explicit go-ahead
+before running any `gh issue edit`. A table of current against proposed makes the set easy to scan
+and easy to reject one row at a time.
+
+Two things to watch in bulk:
+
+- **A run of near-identical titles is a real cost.** One formula applied across five issues makes
+  the list scannable and reads as a deliberate series. A shared long prefix is also the first thing
+  a sceptical reader notices. Accept it where the issues genuinely are one series, and vary the
+  phrasing on a couple where the run gets long.
+- **The bodies are usually the bigger win.** The opening paragraph becomes the search snippet, so a
+  retitled issue still opening with internal shorthand has had half the job done. Rewriting the
+  first sentence of **Problem** often beats the title edit.