Skip to main content
← Back to list
01Issue
FeatureShippedExtensionsPublic
Assigneesskunk-ape

Relationships

#2744 gatorwalk-factory: work-item keys are a title slug plus a short random suffix

Opened by skunk-ape · 9/29/2026· Shipped 9/30/2026

Part of the gatorwalk-factory rebuild (gatorwalk-factory/ in swamp-extensions). Read DESIGN.md, "The model types" ("Keys are gatorwalk's"), first.

Problem

new_key generates <lifecycle>-<8 random base32 characters>, for example cue-k3x9m2qa (generateKey in _lib/work_item_ops.ts). A key is how a person refers to a work item everywhere: in status, the summary report, commands and conversation. A random key tells them nothing about the work.

Decision (Seth)

Keys become a slug of the work's title plus a short random suffix: <lifecycle>-<slug>-<suffix>, for example cue-add-json-output-k3.

  • Why not sequential (cue-7): it needs a counter minted in one place, it resets or reuses numbers when a holder is recreated, and it reads like a tracker id.
  • Why not calver: it is long, hard to say, and repeats what the journal records.
  • Ordering does not matter. Work is often deferred and picked up out of order.
  • The slug is immutable, like any key. If the work changes meaning, the key stays as it is. A person can abandon the item and start a new one when that matters. This is accepted.
  • From a tracker, the slug starts with the ticket's display id, then its title: swamp-extensions-2734-drive-lab-issue-k3. The ticket id in the slug is for reading only. externalRefs stays the only link the code uses, and a Linear identifier that changes when an issue moves team leaves the slug stale, which is accepted too.

Scope

  1. new_key takes a required title input and returns <lifecycle>-<slug>-<suffix>.
    • The slug is lowercase ASCII words joined by -, with other characters dropped, collapsed and trimmed.
    • It is truncated at a word boundary so the whole key fits swamp's 64-character instance-name limit. Check the actual name rules swamp enforces, and cite them.
    • The suffix is short random base32. Choose the length and justify it; the existing free-name check (freshKey) retries on a collision.
    • A title with nothing sluggable left is refused with a clear message.
    • The lifecycle-name prefix stays.
  2. claim (GW-18, _lib/claim.ts) builds its reserved key the same way, from the ticket's display id and title.
  3. start still accepts any unused name, so a person can choose a key by hand.
  4. Update the skill (SKILL.md, references/driving.md, the worked example), README and DESIGN. integration/skill_test.ts must still run the worked example as written.

Done when

  • Unit tests cover:
    • the slug rules: punctuation, unicode, empty after slugging, very long titles, and word-boundary truncation;
    • the 64-character limit with a long lifecycle name;
    • the collision retry;
    • claim's key for both the Lab and Linear adapters.
  • The integration suite passes on the real engine.

Out of scope

  • A stored, mutable title on the work item.
  • Renaming existing work items. Nothing is published, so there is nothing to migrate.

Sequencing

#2734 is editing claim.ts (its guard against issues that issue-lifecycle already drives). Do the new_key part first, and rebase before changing claim.

02Bog Flow
✓OPEN✓TRIAGED✓IN PROGRESS✓SHIPPED+ 1 MOREASSIGNED+ 5 MOREREVIEW+ 8 MOREPR_MERGED+ 2 MORESESSION_SUMMARIZED

Shipped

9/30/2026, 1:30:01 AM

Click a lifecycle step above to view its details.

03Sludge Pulse
skunk-ape assigned skunk-ape9/30/2026, 1:01:21 AM
Editable. Press Enter to edit.

system commented 9/29/2026, 10:44:01 PM

Classified automatically when this issue was filed.

  • Source: Extensions

If you feel this classification is incorrect, add a ripple to tell us so.

Sign in to post a ripple.