Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
85 changes: 54 additions & 31 deletions .agents/skills/asap-pr-authoring/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,29 +8,47 @@ description: Prepare concise ProjectASAP commits and pull-request descriptions.
Organize commits at incremental logical boundaries. Do not include unrelated
working-tree changes or rewrite existing history without explicit authorization.

Write the pull-request description top-down:
Write the pull-request description top-down, so a reviewer learns what changed
and where to look before reading details:

1. **Why**: the user, design, correctness, or MVP need.
2. **What**: the observable behavior and scope changed.
3. **How**: the core implementation or algorithm, without narrating every file.
4. **Key code interfaces added / modified**: the public interfaces the PR adds,
changes, or removes: types, functions, methods, traits, fields, enum
variants, module paths, CLI flags, and wire, file, or document formats.
Write "None" when no interface changes (for example, documentation or tests
only). Use this layout:
1. **Summary**: three lines: the problem, the change, and its effect, with one
concrete example and its numbers (the input, and the output, cost, or
latency before and after).
2. **Review guide**: the base branch and, for a stacked PR, its place in the
stack; the files or functions to read first; which parts are mechanical
(renames, moves, regenerated snapshots) and which need careful review.
3. **Behavior: before → after**: one end-to-end example, from what the user
writes (the workload entry or query with its requirements and data facts, or
the CLI or devtool invocation) to what they get back, before and after this
PR side by side. Say which user, design, correctness, or MVP need it serves.
This replaces separate Why / What / Before / After sections; do not repeat
it elsewhere.
4. **Interfaces**: the public interfaces the PR adds, changes, or removes:
types, functions, methods, traits, fields, enum variants, module paths, CLI
flags, and wire, file, or document formats. Removed interfaces appear as `-`
lines, so no separate deleted list is needed; under the block, give a
one-line reason for any removal whose reason is not obvious. Write "None"
when no interface changes (for example, documentation or tests only). Use
this layout:
- Group by source file. Head each group with links to the files at a fixed
commit, i.e. a permalink to the PR head or the merge commit, not a branch.
- Under each group, put one fenced code block in the source language. It
holds the real declarations copied from the diff: type definitions with
their fields or variants, and function, method and trait signatures with
bodies elided (`;` or `/* ... */`). Mark each change with a trailing
comment (`// new`, `// was X`, `// removed`).
- Under each group, put one fenced ```` ```diff ```` block. It holds the
real declarations copied from the PR's diff (not from memory): type
definitions with their fields or variants, and function, method and trait
signatures with bodies elided (`;` or `/* ... */`). Mark each line by its
first character: `+` for an added line, `-` for a removed line, and a
space for an unchanged context line (the enclosing `struct`, `enum`,
`impl` or `trait` header and closing brace, and unchanged members). A
changed item is its old line(s) with `-` followed directly by its new
line(s) with `+`; a rename is shown the same way. Do not add trailing
`// new`, `// was X` or `// removed` comments: the `+`/`-` marks say it.
A `///` line takes the mark of the declaration it explains (a space
above an unchanged member, `+` above an added or changed one).
- Never collapse members into a comment such as `// ...` or
`/* A, B, C unchanged */`; readers take a collapsed list for a removed
one. When a type is shown, list each of its variants or fields with a
one-line `///` and a marker (`// unchanged`, `// new`, `// was X`,
`// removed`), and put a `///` on the type itself saying whether the type
stays or is removed.
one. When a type is shown, list each of its variants or fields, unchanged
ones as context lines, and put a `///` on the type itself saying whether
the type stays or is removed.
- Explain every interface. Above each declaration, write a short `///` (or
the language's doc-comment form) saying what it is, what it is for, and
when a caller uses it. For an enum variant or an error, say when it is
Expand All @@ -50,7 +68,7 @@ Write the pull-request description top-down:
Use real syntax and numbers, and check them by compiling and running the
example (a test, an example binary or a devtool run) at the linked commit.
See [references/key-code-interfaces-example.md](references/key-code-interfaces-example.md).
5. **Major algorithm changes**: for each algorithm the PR adds, replaces, or
5. **Algorithm changes**: for each algorithm the PR adds, replaces, or
changes in a way that alters its results or cost (search, selection, pruning,
sizing, accuracy composition, cost model, scheduling, execution kernels),
write a short subsection:
Expand All @@ -68,23 +86,28 @@ Write the pull-request description top-down:
- **Assumptions and limits**: when the algorithm does not apply or falls back,
and what it deliberately leaves out.
Write "None" when the PR changes no algorithm (for example, a rename,
documentation, tests, or plumbing only). Keep **How** as the overview and put
the algorithmic detail here.
6. **Before this PR**: the previous end-to-end behavior, limitation, failure
mode, architecture, or workflow.
7. **After this PR**: the new end-to-end behavior and what users, developers, or
operators can do differently.
8. **Verification**: focused tests and applicable end-to-end evidence.

Include a compact before/after example, screenshot, or diagram when it provides
real evidence or makes behavior easier to understand. For significant design
changes, summarize architectural decisions and alternatives.
documentation, tests, or plumbing only). Keep **Summary** as the overview and
put the algorithmic detail here.
6. **Decisions and open questions**:
- **Needs reviewer decision**: each open question and each new public
interface awaiting approval, with its full definition and a concrete
example. Keep an item here until the reviewer answers it.
- **Decided**: each consequential decision with its date, the choice, and
the rejected alternatives; move an item here when it is answered.
Write "None" when there are neither.
7. **Verification**: a table with one row per test scope (crate, suite, or
command): passed / failed / ignored, newly failing compared with the base,
and notes. Give each new test a one- or two-line behavioral purpose, and add
the end-to-end evidence (CLI output, snapshot changes with old → new numbers,
measurements).
8. **Follow-ups**: linked issues, known limitations, and what the PR
deliberately leaves out.

Use the evidence form appropriate to the change: screenshots for visual output,
execution examples for behavior, measurements for performance, or diagrams for
architecture. Explicitly mark an evidence type as not applicable instead of
fabricating it.

State limitations and follow-up work explicitly. Never fabricate screenshots,
Never fabricate screenshots,
test results, measurements, or human approval. Creating or publishing a commit or
PR still requires user authorization.
Original file line number Diff line number Diff line change
@@ -1,121 +1,125 @@
# Example: Key code interfaces section
# Example: Interfaces section

An excerpt from ASAPPlanner #715 (HLL sized from (ε, δ)) in the expected layout:
links per file group at a fixed commit, real declarations with every member
listed and marked, a `///` on every interface, and an end-to-end usage example
links per file group at a fixed commit, real declarations in a `diff` block with
every member listed (`+` added, `-` removed, a space for unchanged context, a
changed item as its `-` old line then its `+` new line), a `///` on every interface, and an end-to-end usage example
whose every variable is commented and whose numbers come from running it.

## Key code interfaces added / modified
## Interfaces

[`crates/types/src/post_asap/sketch.rs`](https://github.com/ProjectASAP/ASAPPlanner/blob/1b5d9577705c7664e711eef9a83ba4f2def0c1da/crates/types/src/post_asap/sketch.rs)

```rust
/// Concrete parameters of one sketch instance; equality compares the built shape.
/// The type stays; this PR adds a field to `Hll` and `Kmv`.
pub enum SketchParams {
/// A UnivMon universal sketch (frequency moments, entropy, distinct count).
UnivMon { // unchanged
/// Top-k heap entries per layer.
heap_size: u32, // unchanged
/// Rows of each layer's Count Sketch.
sketch_rows: u32, // unchanged
/// Columns of each layer's Count Sketch.
sketch_cols: u32, // unchanged
/// Number of sampling layers.
layers: u8, // unchanged
/// The δ the heap was sized for when it answers a distinct count; None = no distinct guarantee.
distinct_failure_probability: Option<f64>, // unchanged
},
/// A KLL quantile sketch.
Kll { // unchanged
/// Compactor capacity.
k: u32, // unchanged
/// The δ `k` was sized for when below 0.01; None = the empirical 99% calibration.
failure_probability: Option<f64>, // unchanged
},
/// A Count-Min sketch.
Cms { // unchanged
/// Counters per row.
width: u32, // unchanged
/// Rows.
depth: u32, // unchanged
},
/// A HyperLogLog distinct-count sketch.
Hll { // unchanged variant; gains relative_error
/// `m = 2^precision` registers.
precision: u8, // unchanged
/// The relative error `precision` was sized for: its guarantee's error bound,
/// at which its failure probability is evaluated.
#[serde(default, skip_serializing_if = "Option::is_none")]
relative_error: Option<f64>, // new: the ε precision was sized for; None = RSE 1.04/√m; ignored by equality
},
/// A DDSketch relative-error quantile sketch.
DDSketch { // unchanged
/// Relative accuracy of each bucket.
alpha: f64, // unchanged
},
/// A Count-Min sketch with a top-k heap.
CmsWithHeap { // unchanged
/// Counters per row.
width: u32, // unchanged
/// Rows.
depth: u32, // unchanged
/// Heap entries.
heap_size: u32, // unchanged
},
/// A KMV (k minimum values) distinct-count sketch.
Kmv { // unchanged variant; gains relative_error
/// The number of smallest hashes kept.
k: u32, // unchanged
/// The relative error `k` was sized for: its guarantee's error bound, at which
/// its failure probability is evaluated.
#[serde(default, skip_serializing_if = "Option::is_none")]
relative_error: Option<f64>, // new: the ε k was sized for; None = RSE 1/√(k-2); ignored by equality
},
/// A Theta distinct-count sketch.
Theta { // unchanged
/// Nominal entries.
k: u32, // unchanged
},
/// A Count Sketch.
CountSketch { // unchanged
/// Counters per row.
width: u32, // unchanged
/// Rows.
depth: u32, // unchanged
},
/// A Count Sketch with a top-k heap.
CountSketchWithHeap { // unchanged
/// Counters per row.
width: u32, // unchanged
/// Rows.
depth: u32, // unchanged
/// Heap entries.
heap_size: u32, // unchanged
},
}
```diff
/// Concrete parameters of one sketch instance; equality compares the built shape.
/// The type stays; this PR adds a field to `Hll` and `Kmv`.
pub enum SketchParams {
/// A UnivMon universal sketch (frequency moments, entropy, distinct count).
UnivMon {
/// Top-k heap entries per layer.
heap_size: u32,
/// Rows of each layer's Count Sketch.
sketch_rows: u32,
/// Columns of each layer's Count Sketch.
sketch_cols: u32,
/// Number of sampling layers.
layers: u8,
/// The δ the heap was sized for when it answers a distinct count; None = no distinct guarantee.
distinct_failure_probability: Option<f64>,
},
/// A KLL quantile sketch.
Kll {
/// Compactor capacity.
k: u32,
/// The δ `k` was sized for when below 0.01; None = the empirical 99% calibration.
failure_probability: Option<f64>,
},
/// A Count-Min sketch.
Cms {
/// Counters per row.
width: u32,
/// Rows.
depth: u32,
},
/// A HyperLogLog distinct-count sketch.
Hll {
/// `m = 2^precision` registers.
precision: u8,
+ /// The relative error `precision` was sized for: its guarantee's error bound, at which
+ /// its failure probability is evaluated. None = RSE 1.04/√m; ignored by equality.
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ relative_error: Option<f64>,
},
/// A DDSketch relative-error quantile sketch.
DDSketch {
/// Relative accuracy of each bucket.
alpha: f64,
},
/// A Count-Min sketch with a top-k heap.
CmsWithHeap {
/// Counters per row.
width: u32,
/// Rows.
depth: u32,
/// Heap entries.
heap_size: u32,
},
/// A KMV (k minimum values) distinct-count sketch.
Kmv {
/// The number of smallest hashes kept.
k: u32,
+ /// The relative error `k` was sized for: its guarantee's error bound, at which
+ /// its failure probability is evaluated. None = RSE 1/√(k-2); ignored by equality.
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ relative_error: Option<f64>,
},
/// A Theta distinct-count sketch.
Theta {
/// Nominal entries.
k: u32,
},
/// A Count Sketch.
CountSketch {
/// Counters per row.
width: u32,
/// Rows.
depth: u32,
},
/// A Count Sketch with a top-k heap.
CountSketchWithHeap {
/// Counters per row.
width: u32,
/// Rows.
depth: u32,
/// Heap entries.
heap_size: u32,
},
}
```

[`crates/asap-aware-mapping/src/accuracy/estimators/hll.rs`](https://github.com/ProjectASAP/ASAPPlanner/blob/1b5d9577705c7664e711eef9a83ba4f2def0c1da/crates/asap-aware-mapping/src/accuracy/estimators/hll.rs)

```rust
/// Pass 1's classic HLL precision for relative error `eps` at failure probability
/// `delta`, without data; plan selection later enlarges it for the source's bound.
pub(crate) fn hll_precision(eps: f64, delta: f64) -> u8; // was hll_precision(eps)
/// Classic HLL's distinct-count guarantee over `source`'s own rows, with δ left
/// symbolic in the source's distinct bound; `None` for a precision outside the contract.
pub(crate) fn classic_guarantee(
precision: u8,
relative_error: Option<f64>, // new parameter
source: &str,
) -> Option<AccuracyGuarantee>;
/// The failure probability given the source's distinct bound; 1 (no certificate)
/// outside the contract's range. Plan selection calls it to bind the symbol.
pub(crate) fn classic_failure_probability(
precision: u8,
relative_error: f64, // new parameter
max_distinct: u64,
) -> f64;
```diff
/// Pass 1's classic HLL precision for relative error `eps` at failure probability
/// `delta`, without data; plan selection later enlarges it for the source's bound.
-pub(crate) fn hll_precision(eps: f64) -> u8;
+pub(crate) fn hll_precision(eps: f64, delta: f64) -> u8;
/// Classic HLL's distinct-count guarantee over `source`'s own rows, with δ left
/// symbolic in the source's distinct bound; `None` for a precision outside the contract.
-pub(crate) fn classic_guarantee(precision: u8, source: &str) -> Option<AccuracyGuarantee>;
+pub(crate) fn classic_guarantee(
+ precision: u8,
+ relative_error: Option<f64>,
+ source: &str,
+) -> Option<AccuracyGuarantee>;
/// The failure probability given the source's distinct bound; 1 (no certificate)
/// outside the contract's range. Plan selection calls it to bind the symbol.
-pub(crate) fn classic_failure_probability(precision: u8, max_distinct: u64) -> f64;
+pub(crate) fn classic_failure_probability(
+ precision: u8,
+ relative_error: f64,
+ max_distinct: u64,
+) -> f64;
```

Usage, end to end: one SQL distinct count with ε = 0.05 and δ = 0.01, planned
Expand Down
Loading
Loading