chore: sync agent standards: key code interfaces with end-to-end usage, example-first issues, interface and efficiency review

.agents/projectasap-managed-files.txt

@@ -4,6 +4,7 @@ AGENTS.md
 .agents/skills/asap-documentation
 .agents/skills/asap-design-review
 .agents/skills/asap-pr-authoring
+.agents/skills/asap-issue-authoring
 .agents/skills/asap-start-work
 .agents/skills/asap-performance-investigation
 .agents/skills/asap-implement-existing-design

.agents/skills/asap-code-review/SKILL.md

@@ -18,6 +18,78 @@ Check whether new conceptual layers, types, or interfaces solve a demonstrated
 need. Flag duplicated definitions and avoid recommending architecture whose cost
 exceeds the stated requirement.
 
+Required step: for the interfaces in the PR, self-ask "any ways to simplify
+or make them more human-readable?", and give the author choices. For every
+type, field, function, method, CLI flag or format the PR adds or changes,
+check whether it could be simpler or easier for a human to read:
+
+- Names are understandable without their comments, and builder or method names
+  match the field names they set or read.
+- Near-duplicate types or functions are merged (for example, two structs that
+  carry the same fields).
+- Reserved or unused fields are removed.
+- A struct holding indexes into another list holds the items themselves.
+- Counts are integers, not `f64`.
+- Display strings live outside planner structs.
+- Planner-internal helpers are not methods on public types.
+- One function replaces a general function plus a special case of it.
+
+Report these in a section **Interface simplifications (author's choice)**. Give
+each option the current signature, the proposed signature, and the trade-off,
+for example:
+
+- `equal_shares(target, metric, of, shares)` and `equal_share(target, metric, n)`
+  → one `per_input_target(target, metric, approximate_inputs)`. Trade-off: only
+  the legacy core uses `shares > 1`; merging needs that core gone first.
+- `whole_result_guarantee(guarantee, output_values: Option<f64>)` →
+  `guarantee.over_whole_result(values_per_result: Option<u64>)`. Trade-off: a
+  method on a public type, but a count that cannot be fractional.
+- `Pass2Candidate { .. }` and `Pass2Of { .. }`, which carry nearly the same fields
+  as ready-formatted strings, plus `SharedSummary { group: usize, members:
+  Vec<usize> }`, which indexes into two other lists → one
+  `Stage1Candidate.pass2: Option<Pass2Candidate>` holding the Pass 1 candidate
+  and the shared build nodes themselves (`shared_builds:
+  Vec<Vec<Rc<OperatorNode>>>`), with display text moved to the devtools.
+  Trade-off: one more rename across the Pass 2 rules, but readers no longer
+  follow indexes.
+
+The author picks; the reviewer does not decide.
+
+Required step: review the implementation's performance complexity
+(efficiency) as well. For the new or changed code paths, check:
+
+- Time and space complexity: quadratic or exponential loops, subset
+  enumeration, recomputation inside loops (for example a reachability walk
+  per node), unnecessary clones of DAGs or roots, and eager enumeration that
+  could be lazy or capped.
+- Allocations on hot paths.
+- How the cost scales with the number of queries, candidates and series.
+
+Each efficiency finding states the complexity, a realistic input size at which
+it hurts, and a concrete cheaper alternative. When the cheaper alternative has
+a trade-off, give the author choices here too.
+
+For example:
+
+- `price` recomputes `query_reach(dag)`, a walk over the whole DAG, for every
+  MatAtQuery node: O(n · (n + e)) per candidate, times every candidate. At
+  Example 3's 972 candidates, if each DAG has about 50 nodes, that is about 2.5·10⁶
+  node visits instead of 5·10⁴. Alternative: compute it once per candidate
+  before the loop and pass it in.
+- Subset enumeration over one sharing group's members is 2^n. It is capped by
+  `MAX_GROUP_MEMBERS = 20` (about 10⁶ subsets). Choices: keep the cap and
+  report a group that hits it, or enumerate lazily and stop at
+  `--max-combinations`.
+
+Review output format, in this order:
+
+1. **Findings**: correctness, regressions and other defects, by severity.
+2. **Interface simplifications (author's choice)**: the options above.
+3. **Efficiency**: complexity, the input size where it hurts, the
+   alternative, and choices where there is a trade-off.
+
+Write "None" under a section with nothing to report.
+
 Check that tests exercise the changed behavior, including relevant unit and
 end-to-end paths. For a bug fix, verify that a regression test would fail without
 the production change.
@@ -26,6 +98,6 @@ For materially affected quality attributes—maintainability, debuggability,
 scalability, understandability, extensibility, performance, and operability—ask
 for measurable evidence where practical. Do not invent numerical precision.
 
-Report findings first, ordered by severity, with precise file and line
-references. State concrete impact and a viable correction. Keep summaries brief;
+Report findings first (section 1 above), ordered by severity, with precise
+file and line references. State concrete impact and a viable correction. Keep summaries brief;
 if no actionable findings remain, say so and identify any material testing gap.

.agents/skills/asap-issue-authoring/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: asap-issue-authoring
+description: Write ProjectASAP GitHub issues that a reader understands without prior context. Use when asked to open, draft or rewrite an issue, a tracking issue, or a follow-up.
+---
+
+# Issues
+
+Write the issue top-down so a reader new to the topic understands the problem
+before the solution:
+
+1. **Problem, by example.** Start with one concrete, minimal example of the
+   problem: the input (a query, a workload, a command, a data shape), what
+   happens today, and what should happen instead. Use real syntax and real
+   numbers; show the current and the desired plan, output, or behavior side by
+   side when that is clearer. Prefer one small example over an abstract
+   description, and add a second only when it shows a different case.
+2. **Why it happens / why it isn't done today.** The cause in the code or the
+   design, named precisely (types, functions, rules), and what already works
+   nearby.
+3. **Proposal or goal.** What a fix or feature would change, at the level of
+   interfaces and behavior, with alternatives when the choice is open.
+4. **Scope and acceptance.** What is in and out of scope, and the test that
+   would show it is done (for a bug, the regression test that fails today).
+5. **Status and related work.** Decisions already made (with dates), why it is
+   deferred if it is, and links to related issues and PRs.
+
+Never invent behavior or numbers: derive the example from the code, a run, or
+a measurement, and say which. Keep people and company names out. Use the
+repository's issue templates when one fits, and keep their sections.

.agents/skills/asap-pr-authoring/SKILL.md

@@ -13,11 +13,48 @@ Write the pull-request description top-down:
 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. **Before this PR**: the previous end-to-end behavior, limitation, failure
+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:
+   - 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`).
+   - 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.
+   - 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
+     produced and whether it reflects bad input, an unsatisfiable request, or an
+     internal bug. For a field, say what it holds and its default. Keep each
+     explanation to one or two lines.
+   - End with a **Usage** example that is end to end, not isolated calls.
+     Start from what the user writes (the workload entry or query with its
+     requirements and the data facts it needs, or the CLI or devtool
+     invocation). Walk through where the system reaches this PR's interfaces:
+     which stage or component calls them, and with what values. End at what the
+     user gets back (for a planner change: the selected plan, its sizes and
+     cost, and each candidate's accepted or rejected line). Every variable gets
+     a comment where it is defined saying what it holds and what it is used for
+     later in the flow; no bare `let x = f(...)` lines, and never a bare
+     internal call such as `size_params(...)` without the flow that reaches it.
+     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. **Before this PR**: the previous end-to-end behavior, limitation, failure
    mode, architecture, or workflow.
-5. **After this PR**: the new end-to-end behavior and what users, developers, or
+6. **After this PR**: the new end-to-end behavior and what users, developers, or
    operators can do differently.
-6. **Verification**: focused tests and applicable end-to-end evidence.
+7. **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