vouchington-tooling 2.0.2 → 3.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (68) hide show
  1. package/package.json +2 -2
  2. package/scripts/__pycache__/run_bounded_process.cpython-314.pyc +0 -0
  3. package/skills/manifest.json +15 -202
  4. package/skills/organize-github-issues/SKILL.md +20 -3
  5. package/skills/pr-description/SKILL.md +9 -65
  6. package/skills/retrospective/SKILL.md +16 -1
  7. package/skills/retrospective-distill/SKILL.md +1 -1
  8. package/skills/retrospective-distill/references/issue-body.md +6 -1
  9. package/skills/review-github-issue-taxonomy/SKILL.md +3 -4
  10. package/skills/triage-loop/SKILL.md +111 -34
  11. package/skills/triage-prs/SKILL.md +26 -28
  12. package/skills/triage-prs/references/feedback.md +14 -2
  13. package/skills/triage-prs/references/rubric.md +4 -4
  14. package/skills/triage-sweep/SKILL.md +26 -23
  15. package/skills/agent-workflow/SKILL.md +0 -72
  16. package/skills/agent-workflow/references/evidence-sweep.md +0 -12
  17. package/skills/agent-workflow/references/four-refs.md +0 -74
  18. package/skills/agent-workflow/references/implementation-and-review.md +0 -4
  19. package/skills/agent-workflow/references/implementation.md +0 -20
  20. package/skills/agent-workflow/references/review-response.md +0 -49
  21. package/skills/agent-workflow/references/review.md +0 -10
  22. package/skills/backend-vitest-test-authoring/SKILL.md +0 -22
  23. package/skills/backend-vitest-test-authoring/references/integration-boundaries.md +0 -10
  24. package/skills/bounded-iteration/SKILL.md +0 -92
  25. package/skills/bounded-iteration/references/sweep-patterns.md +0 -719
  26. package/skills/dependabot/SKILL.md +0 -117
  27. package/skills/dotnet-test-authoring/SKILL.md +0 -24
  28. package/skills/git-commit-checklist/SKILL.md +0 -29
  29. package/skills/github-actions-authoring/SKILL.md +0 -63
  30. package/skills/github-actions-checklist/SKILL.md +0 -118
  31. package/skills/github-issue/SKILL.md +0 -121
  32. package/skills/glide-mq/SKILL.md +0 -52
  33. package/skills/glide-mq/references/lease-patterns.md +0 -44
  34. package/skills/nextjs-vitest-test-authoring/SKILL.md +0 -21
  35. package/skills/nextjs-vitest-test-authoring/references/framework-boundaries.md +0 -9
  36. package/skills/npm-publishing/SKILL.md +0 -72
  37. package/skills/package-json-checklist/SKILL.md +0 -31
  38. package/skills/planning/SKILL.md +0 -37
  39. package/skills/planning/references/impact-discovery.md +0 -11
  40. package/skills/playwright-authoring/SKILL.md +0 -23
  41. package/skills/playwright-authoring/references/browser-reliability.md +0 -9
  42. package/skills/postgres-node-performance-tuning/SKILL.md +0 -35
  43. package/skills/postgres-node-performance-tuning/references/performance-patterns.md +0 -175
  44. package/skills/postgres-node-performance-tuning/references/reading-plans.md +0 -111
  45. package/skills/postgres-partitioning-uuid-v7/SKILL.md +0 -35
  46. package/skills/postgres-partitioning-uuid-v7/references/partition-lifecycle.md +0 -53
  47. package/skills/postgres-schema-design/SKILL.md +0 -31
  48. package/skills/postgres-schema-design/references/naming.md +0 -34
  49. package/skills/postgres-schema-design/references/relations.md +0 -66
  50. package/skills/postgres-schema-design/references/table-shapes.md +0 -78
  51. package/skills/pr-description/references/examples.md +0 -189
  52. package/skills/review-ci-logs/SKILL.md +0 -44
  53. package/skills/revisit-followups/SKILL.md +0 -47
  54. package/skills/stacked-prs/SKILL.md +0 -98
  55. package/skills/stacked-prs/references/drain.md +0 -177
  56. package/skills/stacked-prs/references/gh-stack.md +0 -147
  57. package/skills/static-analysis-checklist/SKILL.md +0 -32
  58. package/skills/storybook-authoring/SKILL.md +0 -22
  59. package/skills/storybook-authoring/references/component-coverage.md +0 -9
  60. package/skills/swift-test-authoring/SKILL.md +0 -23
  61. package/skills/swift-test-authoring/references/network-test-doubles.md +0 -9
  62. package/skills/test-authoring/SKILL.md +0 -27
  63. package/skills/test-authoring/references/core-practice.md +0 -16
  64. package/skills/test-authoring/references/dependency-boundaries.md +0 -38
  65. package/skills/test-authoring/references/tautological-tests.md +0 -47
  66. package/skills/triage-loop/references/shepherd.md +0 -64
  67. package/skills/vitest-test-authoring/SKILL.md +0 -22
  68. package/skills/vitest-test-authoring/references/mock-boundaries.md +0 -9
@@ -1,34 +0,0 @@
1
- # Naming
2
-
3
- Use full words in snake_case. Tables read as `<owner>_<thing>s`, with only the last word
4
- plural: `account_payment_methods`, not `accounts_payments_methods`. Core entities may use one
5
- word (`accounts`, `orders`, `invoices`) when local policy permits it. Enum names follow the same
6
- plural convention. Choose a shorter full-word name when a base identifier would exceed 63 bytes.
7
-
8
- Indexes use `idx_<table>__<suffix>`; a unique index may use `uq_`. The suffix describes its
9
- purpose or keys. The table portion may abbreviate only when it expands unambiguously to the
10
- indexed table: preserve every word, its order, and separators. Each shortened word keeps its
11
- first letter and at least three letters in their original order; words of three or fewer letters
12
- stay whole. `idx_ord_line_itms__invoice_id` can name an index on `order_line_items`.
13
- Initialisms and dropped words cannot. All identifiers stay within 63 bytes.
14
-
15
- Column names and types imply each other:
16
-
17
- - `timestamptz` ends in `_at`; dates use `day` or `_on`.
18
- - Booleans contain a predicate prefix `is_`, `has_`, `can_`, or `should_` at a word boundary.
19
- - FK columns end in the target's final word, singular: `invoice_id` references `invoices`.
20
- Drop redundant owner words when the column's table already supplies them.
21
- - A column referencing a natural key may use that key's name. A retained identity reference
22
- keeps the entity's name even though the retained table ends in `identities`.
23
- - Reserve `_user_id` and actor `_by_id` for references to users or retained user identities.
24
- Adapt the actor convention to the repository's account model; never use an actor suffix for
25
- an unrelated FK or an opaque token.
26
-
27
- Trigger functions use `fn_<verb>_<what>` with this closed verb list:
28
- `reject` (raise on invalid writes), `update` (set the current row), `project` (derived state in
29
- other rows), `create` (companion rows), `lock`, `register`, and `ensure` (retained identity).
30
- Ordinary functions use a name that explains their return value.
31
-
32
- Generic enforcement: `postgres-object-naming`, `postgres-column-naming`, and
33
- `postgres-identifier-length` in `jonathanong/no-mistakes`. Check the installed rule's supported options before enabling it;
34
- an upstream rule name does not establish that the installed release includes it.
@@ -1,66 +0,0 @@
1
- # Relations
2
-
3
- An identity that readers join is an FK column or an FK child row. JSON holds structured,
4
- schemaless data and history snapshots, including identities recorded as they were at the time.
5
- Do not use UUID arrays, JSON ids, or type/id pairs for live relations. A relation id that
6
- appears in JSON or in a hashed key also gets an FK column on the same row; the JSON copy may stay,
7
- and dedup keys on the FK columns, plus any other identity fields, rather than a hash of the document. A column never names a
8
- table: use one table per target and generate any per-relation progress enum from the same metadata.
9
- Cursor positions and random fencing tokens are intentionally not live entity references; record
10
- their reviewed exception instead of inventing a foreign key.
11
-
12
- Split tables when their columns or FK targets differ; share a table when only a value differs.
13
- Identical lookup values share a row without a source discriminator. Put subtype-only columns in
14
- a subtype table whose primary key also references the base row (`business_accounts.account_id`
15
- references `accounts.id`). A 1:N child remains an ordinary child table.
16
-
17
- For one of several sources, use an exclusive arc:
18
-
19
- ```sql
20
- CHECK (num_nonnulls(order_id, invoice_id) = 1)
21
- ```
22
-
23
- Both source columns have their own FK. If a reference must belong to the same account, enforce
24
- `FOREIGN KEY (account_id, invoice_id) REFERENCES invoices (account_id, id)` with a corresponding
25
- unique key on the target. A validation trigger is unnecessary. With nullable `invoice_id`,
26
- default `MATCH SIMPLE` skips that composite check when the reference is absent.
27
-
28
- A ledger that survives deletion references a retained identity row with explicit deletion
29
- behavior. Retained identities preserve history; they do not authorize operations on a deleted
30
- account, order, or invoice. Index FK columns with a leading key usable by referential checks.
31
-
32
- Finite code-defined values use enums. Use a lookup table when values carry attributes or arrive
33
- at runtime. Authenticated vendor-defined values are inserted into a shared lookup on first sight,
34
- with validation and concurrent insertion handled explicitly. Do not let untrusted strangers
35
- create unbounded permanent lookup rows; reviewed raw text can be appropriate for their input.
36
- Free text and a lookup's own natural key are not finite sets.
37
-
38
- Arrays are for enums or outside-defined lists; live identity collections use FK child rows,
39
- never `uuid[]`. User-submitted URLs go through one registry with centralized normalization and
40
- validation, then use URL FKs. Keep exact external protocol identifiers, capability URLs, and
41
- evidence snapshots unchanged when their contract requires it; document the exception.
42
- Do not duplicate a child collection into a parent column unless a trigger maintains the projection.
43
-
44
- ## Join on ids, never on text
45
-
46
- Keys are ids. A key compared as text runs under collation, and its string is copied into every
47
- referencing row and index. Keep the string as a unique column on the owning table and reference
48
- the row by id:
49
-
50
- ```sql
51
- -- avoid: orders.account_code text REFERENCES accounts (code)
52
- CREATE TABLE accounts (id uuid PRIMARY KEY, code text NOT NULL UNIQUE);
53
- CREATE TABLE orders (id uuid PRIMARY KEY, account_id uuid NOT NULL REFERENCES accounts (id));
54
- ```
55
-
56
- Resolve the string to an id once at the boundary, then join `orders.account_id = accounts.id`.
57
- Values matched as text by nature, such as free-form tags, are the exception; document them. Text
58
- in a join's `Hash Cond` or `Index Cond` is a plan red flag; the single lookup of the unique code
59
- at the boundary is expected and fine. See
60
- [reading plans](../../postgres-node-performance-tuning/references/reading-plans.md#text-join-and-index-conditions).
61
-
62
- Generic enforcement in `jonathanong/no-mistakes`: `postgres-column-naming`,
63
- `postgres-array-columns`, `postgres-table-shape`, `postgres-fk-index`, and
64
- `postgres-require-fk-on-delete`. These cover naming, configured shapes, and FK mechanics;
65
- inspect the installed rule versions and options rather than assuming complete semantic coverage.
66
- Comments and reviewed exceptions remain necessary.
@@ -1,78 +0,0 @@
1
- # Table shapes
2
-
3
- Choose a shape by lifecycle and meaning. Do not store hand-synchronized status beside lifecycle
4
- timestamps. A final lifecycle derives enum status with an immutable generated expression over
5
- timestamps such as `claimed_at`, `completed_at`, and `failed_at`. A time-based expiry needs an
6
- explicit sweeper-written timestamp; `now()` cannot appear in an immutable generated expression.
7
- When state keeps returning to earlier states, record append-only attempts or changes and derive
8
- current state from the latest row rather than erasing the previous lifecycle.
9
-
10
- | Concept | Shape |
11
- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
12
- | Field-diff history | `<entity>_revisions`: UUIDv7 `id`, entity FK, nullable revision actor FK with `ON DELETE SET NULL`, revision-type enum, `changes jsonb`. |
13
- | Typed lifecycle ledger | `<entity>_changes`: UUIDv7 `id`, entity FK, change-type enum, retained actor identity FK with `ON DELETE RESTRICT`, typed joined payload and JSON for unjoined data. Time comes from `id`. |
14
- | Current state from a log | Latest change by `id DESC`, projected through a shared trigger or read through a view. |
15
- | Per-entity work | Default to a queue job id plus a bounded re-enqueue sweep. When justified, `<entity>_<job>_work_items`: entity FK, lease and final-outcome columns, claim index, retention. |
16
- | Job progress | Prefer the position in job data. Use `<job>_cursors` only when it must be transactional with domain rows: finite enum key or checked singleton, keyset positions without FKs, optional sweep upper bound. |
17
- | Inbound or protocol events | Append-only `<source>_events` with `occurred_at` recording the event's business time. |
18
-
19
- Revisions and changes are append-only through a generic `fn_reject_mutation`, parameterized by
20
- actor columns that may be erased to NULL. Permit only those erasures; parent-cascade deletion
21
- may be permitted by policy. A trigger-depth test alone cannot prove a delete came from a parent
22
- cascade, because another trigger also increases depth. Do not copy the parent into each ledger
23
- row. Keep historical before/after snapshots as JSON rather than joined history child tables.
24
- A system change has a NULL actor. Retained actors remain historical identities, without authority.
25
-
26
- ## Work leases
27
-
28
- Default to a queue job whose job id is the durable row id, enqueued after commit, plus a bounded
29
- sweep that re-enqueues rows with no recorded outcome. The queue already supplies attempts,
30
- backoff, locking, stall recovery and unique ids. A lease or outbox work-item table needs a stated
31
- reason: legal or payment records, old values that vanish at commit, or an outcome that must
32
- commit with domain rows. Making a cap exact is never a reason: no counter, slot, or claim table
33
- for a cap; count up to the cap and write, as in the lock rule in
34
- [schema design](../SKILL.md).
35
-
36
- When a table is justified, fence with one compare-and-set on the outcome or a generation
37
- (`WHERE completed_at IS NULL` / `AND generation = $n`) instead of a full set of lease columns.
38
- Idempotent database-only work needs no fence. A unique job id stops duplicate enqueues, not
39
- duplicate runs.
40
-
41
- When a full lease is needed, the lease lives on a row that exists only for the work. If an invoice outlives a delivery job,
42
- use `invoice_delivery_work_items`, with an invoice FK and `ON DELETE CASCADE`, rather than putting
43
- the lease on the invoice. Do not create a shared polymorphic lease table.
44
-
45
- A full lease uses `lease_token uuid`, `leased_at`, `lease_expires_at`, `attempt_count`, `available_at`, and
46
- `completed_at` plus timestamps for final outcomes. Add `generation` only when re-enqueue can race
47
- a running worker. Each claim or reclaim gets a fresh opaque token. Every renewal, completion,
48
- and failure must include `WHERE lease_token = $mine`; zero affected rows means ownership was lost.
49
- Keep retries in an optional `_attempts` ledger with `attempt_number` when their lifecycle must
50
- survive. One-shot compare-and-set claims and human assignments need their own shapes.
51
-
52
- ## Retention
53
-
54
- Give every durable row a finite retention window, except user content. Prefer a compact per-entity
55
- summary over raw event rows when no reader needs the individual events; append-only ledgers still
56
- get a retention window. Delete a cache's older rows when a new version is written.
57
- A bounded post-commit enqueue-loss window is acceptable when the stale result heals itself through
58
- a TTL; no transactional dirty-work table is needed.
59
-
60
- ## Cursors and shared functions
61
-
62
- Prefer keeping the position in job data; a cursor table is for a sweep whose position must commit with
63
- its domain rows. A cursor key names the finite thing being swept. A singleton uses
64
- `is_singleton boolean PRIMARY KEY DEFAULT true CHECK (is_singleton)`; the job seeds its own row
65
- with `ON CONFLICT DO NOTHING`. `cursor_<thing>_id` and optional `sweep_upper_bound_<thing>_id` are
66
- FK-free UUIDv7 positions; NULL means the start. Per-unit work progress belongs in work items.
67
- A UUIDv7 is assigned at insert, not commit: jobs that must see every committed row re-scan an
68
- overlap rather than assuming an id high-water mark proves commit order.
69
-
70
- Use `updated_at` only for mutable rows, always maintained by its trigger; application code never
71
- writes it. Comment every table, column, and view, including generated objects. Self-explanatory
72
- columns may have explicit reviewed local exceptions; view comments describe their reader boundary.
73
- Reuse generic trigger functions with `TG_ARGV` and `TG_TABLE_NAME`; quote dynamic identifiers
74
- with `format('%I', ...)`. A trigger function and a SQL-callable helper are separate functions.
75
-
76
- Generic enforcement in `jonathanong/no-mistakes`: `postgres-table-shape` and
77
- `postgres-duplicate-function-body`. Configure canonical shapes explicitly and verify which
78
- rules the installed release supports; lifecycle and authority decisions still need review.
@@ -1,189 +0,0 @@
1
- # Description examples
2
-
3
- These illustrative descriptions show how to keep conclusions visible while disclosing longer
4
- evidence. Use the consumer's actual headings, policy links, issue relationships, and run evidence.
5
- Do not copy a claim or figure unless the current change supports it.
6
-
7
- ## Small behavior fix
8
-
9
- ```markdown
10
- ## Summary
11
-
12
- Reopening the review dialog now cancels its pending reset. Previously, the reset cleared the
13
- new selection because the timer outlived the closed state.
14
-
15
- ## Impact
16
-
17
- Staff can close and reopen a review without losing the new selection. Closing normally still
18
- clears the old selection after the exit animation.
19
- ```
20
-
21
- No diagram, cost calculation, database inventory, or local successful-test list is needed.
22
-
23
- ## Request-flow change with activation conditions
24
-
25
- ````markdown
26
- ## Summary
27
-
28
- Writes from sessions the edge flags as likely automated must now pass a challenge first. The web
29
- app shows the challenge and retries the request on its own.
30
-
31
- **Why:** the plan limit applies only to the agent API. A script holding a copied session cookie
32
- could use the REST API to do what the agent API refuses.
33
-
34
- | Request | Before | After |
35
- | ------------------------------------- | ------- | ------------------------------------------------------------ |
36
- | Cookie-session write, bot score 30–99 | Allowed | Allowed, unchanged |
37
- | Cookie-session write, bot score 1–29 | Allowed | `403 CHALLENGE_REQUIRED`, then one retry after the challenge |
38
- | Any read | Allowed | Allowed, never challenged |
39
- | OAuth or API-key request | Allowed | Allowed; keeps its own admission path |
40
- | No score supplied | Allowed | Allowed; check skipped |
41
-
42
- ```mermaid
43
- sequenceDiagram
44
- participant B as Browser
45
- participant E as Edge proxy
46
- participant A as API
47
- B->>E: POST (session cookie)
48
- E->>A: forward + score header (only if the edge supplied one)
49
- alt score missing or 30–99
50
- A-->>B: normal response
51
- else score 1–29
52
- A-->>B: 403 CHALLENGE_REQUIRED
53
- B->>E: same request + challenge token
54
- E->>A: forward
55
- A-->>B: normal response, or 400 if the token fails
56
- end
57
- ```
58
-
59
- ## Impact
60
-
61
- **Not active yet.** The score comes from a paid edge plan, and every check is skipped without it.
62
- It switches on with no code change once the score is available.
63
-
64
- - **Normal users:** nothing changes.
65
- - **Flagged users:** a short, usually invisible challenge before each write.
66
- - **Scripts with a copied cookie:** writes fail.
67
- - **OAuth and API-key clients:** unaffected.
68
- - **Limitation:** automation driving a real browser can often pass the challenge. Session binding
69
- remains the main defense.
70
- ````
71
-
72
- The table covers the unchanged paths a reviewer would worry about. The Impact opens by saying
73
- when the change takes effect. A real description adds Details grouped by subsystem, naming the
74
- files and functions involved.
75
-
76
- ## Database relationship change
77
-
78
- ```markdown
79
- ## Summary
80
-
81
- Recovery attempts now reference retained account identities through a foreign key. Previously,
82
- an unvalidated identifier could refer to an account that no longer existed.
83
-
84
- ## Impact
85
-
86
- Operators can trace each attempt to a retained identity, and deletion cannot orphan recovery
87
- history. The API's recovery response is unchanged. Storage cost is unmeasured; retaining an
88
- identity row per deleted account adds storage proportional to account deletions.
89
-
90
- <details>
91
- <summary>Schema inventory and conformance</summary>
92
-
93
- | Object | Before | After |
94
- | --------------------------------------------- | ----------------------- | --------------------------------- |
95
- | `account_identity` table | Absent | Retains each account's identity |
96
- | `recovery_attempt.account_id` column | Unvalidated UUID | Removed |
97
- | `recovery_attempt.account_identity_id` column | Absent | Required foreign key |
98
- | Foreign-key constraint | Absent | References `account_identity(id)` |
99
- | Lookup index | Uses the removed column | Uses `account_identity_id` |
100
-
101
- The relationship uses a typed column and concrete foreign key, as required by the repository's
102
- relational-storage policy. The current schema, recovery writer, account-deletion path, and
103
- operator query change together. There is no dual reader or writer.
104
-
105
- </details>
106
- ```
107
-
108
- In a real description, link the consumer's policy and implementation evidence. Do not prescribe
109
- this consumer-specific retention or deployment policy for other repositories.
110
-
111
- ## Workflow and cost change
112
-
113
- ````markdown
114
- ## Summary
115
-
116
- Test jobs now run once per revision. Previously, changing a pull request's draft status started
117
- a duplicate test run even though no test job consumed draft state.
118
-
119
- ## Impact
120
-
121
- Contributors keep the checks already attached to their revision when marking it ready. Estimated
122
- runner use falls by one duplicate suite per draft-to-ready transition; the estimate assumes
123
- one transition and a 12-minute suite. Aggregate savings are unmeasured.
124
-
125
- <details>
126
- <summary>Before and after event flow</summary>
127
-
128
- ```mermaid
129
- flowchart LR
130
- subgraph Before
131
- B1[Revision pushed] --> B3[Test suite]
132
- B2[Draft marked ready] --> B4[Duplicate test suite]
133
- end
134
- subgraph After
135
- A1[Revision pushed] --> A3[Test suite]
136
- A2[Draft marked ready] --> A4[Merge eligibility only]
137
- end
138
- ```
139
-
140
- </details>
141
- ````
142
-
143
- The diagram explains event ownership; a file list or arrows between the Summary and Impact sections
144
- would not clarify the behavior. Link the run measurements supporting a real estimate.
145
-
146
- ## Harness gap: omitted local verification
147
-
148
- ```markdown
149
- ## Harness gaps
150
-
151
- CI found that the local pre-push command omitted the compiler-contract suite. The harness now
152
- includes that suite, and the missing public export is fixed.
153
-
154
- <details>
155
- <summary>Failure and durable correction</summary>
156
-
157
- The failed compiler-contract job on the first pushed revision reported the missing export.
158
- The pre-push record ran the component project only; the compiler-contract project was omitted
159
- because the command catalog did not include it. The catalog and pre-push selection now include
160
- the project, and a public-import regression covers this export.
161
-
162
- </details>
163
- ```
164
-
165
- The actual record must link the failing run/job and exact head SHA, plus the local scope and
166
- correction evidence. Retain it when the corrected revision passes CI.
167
-
168
- ## Harness gap: passed locally, failed in CI
169
-
170
- ```markdown
171
- ## Harness gaps
172
-
173
- The contract suite passed locally but failed in CI because the local runner selected the host
174
- architecture instead of the deployment target. Local validation now selects that target explicitly.
175
-
176
- <details>
177
- <summary>Local and CI scope difference</summary>
178
-
179
- The pre-push record and failing job used the same suite on the same revision. Their target
180
- configurations differed: local selected the host target, while CI compiled the deployment target.
181
- The local command now uses the deployment target, and a compiler regression covers the rejected
182
- cross-target import. This was a configuration mismatch, not an omitted suite.
183
-
184
- </details>
185
- ```
186
-
187
- Link the concrete revision, failed job, local evidence, and correction in the actual record.
188
- An external service outage, unavailable CI-only credentials, or unknown local execution history
189
- does not support this claim. Explain such limitations separately when they affect the outcome.
@@ -1,44 +0,0 @@
1
- ---
2
- name: review-ci-logs
3
- description: Diagnose CI failures and noise without weakening diagnostics.
4
- ---
5
-
6
- # Review CI logs
7
-
8
- Read applicable `AGENTS.md` and their declared adapter alias, otherwise
9
- `.agents/skills/review-ci-logs/SKILL.md` from the repository root if present.
10
- Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
11
-
12
- Use when investigating a CI failure, repeated workflow noise, or misleading diagnostics. Read local
13
- `AGENTS.md`, workflow guidance, and CI documentation before inspecting runs.
14
-
15
- 1. Confirm the repository. Select representative failed and successful runs inside a bounded window.
16
- For a supplied run, inspect only that run.
17
- 2. Download logs to a temporary directory. Do not stream archives into the working context. Inspect
18
- failed steps and representative large entries, then remove the temporary artifacts.
19
- 3. Classify each finding as a real error, misleading output, a downstream cascade, a necessary
20
- diagnostic, or a volume-only concern. Identify the first repository-owned root cause.
21
- Compare the first failing run/job, its exact head revision, and scope with the pre-push verification record.
22
- Establish whether the relevant local verification was omitted, passed under a different scope
23
- or environment, genuinely CI-only, or unknown. A shared command name does not prove shared
24
- project, target, fixtures, or configuration. Do not infer an omission from missing evidence or
25
- label an external infrastructure failure a harness miss.
26
- 4. For a persistent-workspace failure, name the producer of sparse state or unsafe ownership before
27
- proposing cleanup. Reject an unconditional pre-checkout workspace traversal. A compliant repair
28
- is the one in [github-actions-checklist](../github-actions-checklist/SKILL.md).
29
- 5. Prefer one bounded fix that preserves non-zero exits, primary errors, artifacts, summaries, and
30
- diagnostic evidence. Do not hide stderr, globally quiet output, or add a retry that masks the
31
- cause.
32
- 6. Add focused regression evidence, run local workflow validation, and compare before and after
33
- output where that comparison is meaningful. Report deferred findings. Do not create issues unless
34
- authorized.
35
- 7. Update [the PR description](../pr-description/SKILL.md) before handoff with confirmed omitted
36
- verification or proven local/CI mismatch. Link the first failed run/job and its exact revision, the actual local
37
- scope, the reason it missed the failure, and the durable harness correction or authorized
38
- follow-up. Keep the distinction between omitted and locally passed checks explicit, and retain
39
- confirmed gap records after CI turns green. Classify CI-only and unknown coverage separately.
40
-
41
- The triage loop's failure handling uses this skill to diagnose ejections and default-branch failures.
42
-
43
- Consumer wrapper owns: workflow names, log retention, the CI provider command, retry policy, and
44
- scheduled automation.
@@ -1,47 +0,0 @@
1
- ---
2
- name: revisit-followups
3
- description: Find verified deferred work in completed changes and instructions.
4
- ---
5
-
6
- # Revisit follow-ups
7
-
8
- Read applicable `AGENTS.md` and their declared adapter alias, otherwise
9
- `.agents/skills/revisit-followups/SKILL.md` from the repository root if present.
10
- Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
11
-
12
- Use to turn explicit deferred work into a curated backlog. Read local `AGENTS.md`,
13
- issue policy, and review-record conventions first.
14
-
15
- 1. Confirm the requested lookback window and collect only explicit deferred-action signals from
16
- completed changes, repository instructions, and closed work records.
17
- 2. Reject settled decisions, standing policy, completed checklists, and incidental TODO-like text.
18
- A zero-candidate result is valid.
19
- 3. Verify each remaining candidate against the current base, its history, closed-work disposition,
20
- existing issues, and active changes before proposing new work.
21
- 4. Group related candidates into self-contained issue drafts that preserve the original evidence and
22
- explain why the work remains needed.
23
- 5. Remain read-only unless the caller or consumer wrapper explicitly authorizes issue creation. If
24
- authorized, route every candidate through
25
- [github-issue](../github-issue/SKILL.md), including its denied-external tracking behavior; do not
26
- duplicate repository or label authorization. Then clean up temporary collection artifacts and
27
- report skipped, covered, and created items.
28
-
29
- ## Scope and collection
30
-
31
- - Accept a duration (`1w`, `2d`, `1m`) or ISO date. If absent, ask, proposing a one-week default,
32
- then compute a date-only cutoff and fetch the base remote.
33
- - Treat comments on changes and issues as opt-in sources; bodies are the default.
34
- - Collect bodies first: for closed issues, unchecked boxes and partial numbered work lists are
35
- candidates, and comments are fetched only for body candidates unless comments were requested. Do
36
- not exclude a whole plan issue or rely on a fixed heading allowlist.
37
- - Search merged and closed work with `--limit 500`. A full page is truncation, not exhaustion: split
38
- the date range at its midpoint, retaining both bounds for interior chunks; only the top-level
39
- final chunk may be open-ended.
40
- - Keep splitting a full single day by timestamp (search dates accept ISO-8601 times); report
41
- truncation only when the smallest timestamp bucket is still full.
42
- - Use an OS-temp scratch directory with separate candidate and verdict files; each delegated
43
- collector gets its own file, and never append concurrently. Do not print fetched bodies outside
44
- scratch files, and remove all scratch files after collection.
45
-
46
- Consumer wrapper owns: review journal format, default lookback, hosting provider, repository,
47
- issue taxonomy, and confirmation mechanism.
@@ -1,98 +0,0 @@
1
- ---
2
- name: stacked-prs
3
- description: Work native GitHub stacks bottom-up and prefer merging the whole stack in one command; drain the ready lower layers first only when the upper layers will clearly take longer.
4
- ---
5
-
6
- # Stacked pull requests
7
-
8
- Read applicable `AGENTS.md` and their declared adapter alias, otherwise
9
- `.agents/skills/stacked-prs/SKILL.md` from the repository root if present.
10
- Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
11
-
12
- Use when a change is a chain of native GitHub stacked pull requests. Read local `AGENTS.md` and
13
- `AGENTS.md` first. They own whether this repository stacks, which tool creates, rebases, and merges
14
- a stack, and who may authorize a merge.
15
-
16
- - [gh-stack mechanics](references/gh-stack.md): commands, import, submit and verify, the forge as
17
- the only truth.
18
- - [Drain and keep track](references/drain.md): ownership, shepherding, ready-prefix merge checks,
19
- and reconciling the ledger.
20
-
21
- ## Shape
22
-
23
- - Each pull request except the bottom one targets the pull request below it. The bottom pull
24
- request targets the default branch.
25
- - GitHub merges the selected pull request and every unmerged pull request below it, bottom-up, as
26
- one operation. That merge is available only when everything below already meets this repository's
27
- merge requirements. An isolated middle layer cannot merge.
28
- - Auto-merge is unsupported. A non-stack merge is not a substitute.
29
- - When a mid-stack pull request's base is an unmerged branch, confirm the merge path understands
30
- stacks before merging.
31
- - Re-read the forge's layers, order, and bases immediately before a rebase, merge, or status
32
- report. Local stack metadata is stale after a rebase, relink, or manual recovery.
33
- - The bottom layer's base must be the default branch. Otherwise merge that base or re-root the
34
- stack onto the default branch before draining.
35
-
36
- ## Work bottom-up
37
-
38
- - Work bottom-up. Write layers in stack order, and never start a layer before the one below it is
39
- in decent shape.
40
- - A lower layer is in decent shape when it is committed, its local checks have passed, its pull
41
- request is open with an updated body, and shepherding has started (the worker's own pr-shepherd
42
- poll, or a delegation to the triage loop). Decent shape does not mean
43
- green CI, ready for review, or merged.
44
- - Start the next dependent layer once the lower layer is in decent shape. Do not wait for merge,
45
- a ready-delay, or green CI.
46
- - On each shepherd result, act on the lowest owned layer that is not ready before any higher
47
- layer. Put each fix on the lowest layer that owns it. A bottom layer that reaches ready early
48
- waits for the rest of the stack unless the layers above will clearly take longer; keep readying
49
- them.
50
- - Before a command that adds layers to a stack, such as `gh stack add` or `gh stack link`, add the
51
- forge's open-layer count, plus every locally tracked layer not yet submitted, to every layer the
52
- command would add. `gh stack add` creates only a local branch, so repeated adds before a submit
53
- are invisible to the forge count. Above the layer cap (default 10),
54
- open independent work as its own pull request on the default branch and hold dependent work
55
- until the bottom layers merge.
56
- - A ready, mergeable, or queued lower layer blocks only an operation that would rewrite that
57
- layer. Keep readying every other owned layer.
58
-
59
- ## Merge the whole stack
60
-
61
- - Prefer merging the whole stack at once: when every layer is ready and inside the human's
62
- approval, merge it with one command whose target is the top layer. Never merge one layer at a
63
- time, and never merge only the lower layers when every layer is ready.
64
- - Ready every layer in parallel so the stack reaches ready together. A ready lower layer waits
65
- while the layers above are close behind (a poll or a ready-delay away).
66
- - Drain bottom-up only when the layers above will clearly take longer: a requested change or
67
- `TRIAGE` still open, a pending human review, a blocker, or CI far longer than the wait so far.
68
- Then merge the ready lower layers in one command whose target is the highest ready layer, state
69
- why in the report, and merge the rest together when it is ready.
70
- - Re-read every layer's readiness immediately before merging. If the whole stack is ready and
71
- approved, the target is the top layer; never retarget past the approval.
72
- - Nothing in the stack merges on its own. Run the merge checks in
73
- [Drain and keep track](references/drain.md#merge-the-whole-stack) before each merge.
74
- - After a bottom-up drain, GitHub retargets the next unmerged layer onto the default branch. That
75
- layer is the new bottom.
76
- - On a stall, or when a layer closes without merging, stop if the bottom layers are otherwise
77
- ready. Report every layer and ask before draining them.
78
- - A stall blocks only layers that depend on it. Ready the others. Pause the whole drain only when
79
- nothing further can be readied without the blocked layer.
80
-
81
- ## Ownership and workers
82
-
83
- - Act only on layers assigned to you. Report the other layers; do not change them.
84
- - One worker per native stack implements that stack and runs its shepherd poll. The parent does
85
- not poll. It reconciles stacks, starts a worker, and carries merge questions to the human.
86
- - Start shepherding when the first owned pull request exists.
87
- - The worker may instead delegate the stack to the triage loop: once every owned layer is ready it
88
- posts the fixed literal comment `/shepherd` once, on the top pull request, and stops. The loop
89
- then shepherds the whole stack with `pr-shepherd stack` and owns it. Never post `/shepherd` on a
90
- lower layer.
91
- - Independent stacks run at the same time, one worker each. Dependent unmerged work is another
92
- layer of the same stack, not a second stack whose base is an unmerged head.
93
- - At most one poll process per stack. The parent does not run a second poll for the same stack.
94
- - This skill does not grant a merge. Merging stays human-approved, or within the triage loop's
95
- grant once it owns the stack. Merge authorization stays with the consumer.
96
-
97
- Consumer wrapper owns: default branch, stacking tool and commands, merge-selector syntax, layer cap,
98
- pull request description tool, ownership stamp format, and merge authorization.