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
49 changes: 44 additions & 5 deletions skills/pt-snap-helper/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -94,10 +94,42 @@ value; `--opt=value` and numeric tokens do not consume the next
argument). Text mode still writes `Error:` lines to stdout.

This skill itself does not run analysis queries. The diagnostic skills own
those commands. For an existing SnapshotDB, point the next skill at
`pt-snap capabilities --json` and `pt-snap overview '<db_path>' --json`
before diagnosis so it does not need per-template `--template-info` or a
separate metadata probe.
those commands and the shared preflight below, including when invoked directly.

### Shared diagnostic preflight contract

For an existing SnapshotDB, the normal prerequisite probes are
`pt-snap capabilities --json` and `pt-snap overview '<db_path>' --json`.
The complete `templates[]` catalog supplies the same parameters, `output_schema`,
and field semantics as per-template `--template-info`; check every template
required by the selected skill by name. Stop on a missing required template or
failed probe and report the exact failure; do not substitute raw SQL.

Read `overview.import_metadata.status` (the `import_metadata` field in the
overview JSON), not just exit code 0 or outer `ok: true`. Stop on `invalid`
metadata or schema errors. Continue with `available`, or with legacy
`unavailable` and reason `metadata_missing` after recording unknown import
provenance. Stop on any other status/reason or incomplete result. Overview also
provides devices and trace bounds; validate the selected device against it.

Reuse complete successful results already obtained in this conversation only
for the same CLI/Python environment and unchanged database target. Capabilities
must match the current CLI version; overview must match the resolved absolute
database path. A summary, truncated output, changed environment/version, changed
database, or unknown result identity is not reusable. Fetch only the missing or
stale result. Direct invocation of a diagnostic skill performs the same complete
validation; helper use is not a prerequisite. Do not re-emit a reused catalog or
repeat per-template probes. Normal discovery costs 2 calls from cold, 1 with one
reusable result, and 0 with both; measure tool-call count and output bytes
separately, since the full catalog can be larger than individual probes.

Capabilities does not describe report command options. Keep
`pt-snap report peak-memory --help` when the selected workflow requires report
validation (mandatory for peak breakdown, conditional for fragmentation).
Availability/focus/report-help checks are separate from the two discovery calls.
Missing-focus recovery below is the explicit metadata-first exception: after
user confirmation, inspect metadata first, then obtain/reuse capabilities and
overview and apply these same checks. Metadata alone does not replace overview.

## Routing matrix

Expand Down Expand Up @@ -131,7 +163,8 @@ A SnapshotDB is a pt-snap SQLite database (typically `.db`) with a
1. Confirm the goal is leak, peak, or fragmentation.
2. Tell the next skill to start with `pt-snap capabilities --json` and
`pt-snap overview '<db_path>' --json` (overview first, then diagnose).
Pass the database path and device if the user supplied them.
Pass the database path and device if the user supplied them, plus any complete
reusable results under the shared preflight contract above.
3. Hand off to the matching diagnostic skill. Do not run leak, peak, or
fragmentation query templates from this helper.
4. Do not run `pt-snap focus <database_path>` to persist a new focus from this
Expand Down Expand Up @@ -166,6 +199,12 @@ explicit path and do not enter this branch.
re-resolve device from the confirmed database. This helper must not run
metadata, query, import, or persist focus.

The diagnostic skill must stop on invalid metadata or schema errors in this
metadata-first exception. Legacy `unavailable` with reason `metadata_missing`
permits continuing with unknown import provenance recorded. Then apply the
shared capabilities/overview preflight; do not reuse the missing target's
overview or treat metadata as an overview substitute.

This helper may mention that `pt-snap overview '<db_path>' --json` and
`pt-snap capabilities --json` exist. Running those orientation commands
belongs to the diagnostic skill. Do not import pickle or persist focus.
Expand Down
56 changes: 42 additions & 14 deletions skills/pt-snap-memory-fragmentation/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -99,30 +99,58 @@ explicit path and do not enter this branch.
reason `metadata_missing`; record unknown import provenance and do not force
a re-import. Stop on schema errors or invalid metadata.

### 3. Verify metadata and required templates before diagnosis
### 3. Verify capabilities and the database in two calls

Run these checks before any diagnostic query:
Apply the shared diagnostic preflight contract in `pt-snap-helper`, even on
direct invocation. Run only the probes whose complete results are not reusable:

```bash
pt-snap metadata "<db_path>" --json
pt-snap query --template-info memory_peak
pt-snap query --template-info allocator_gap
pt-snap query --template-info allocation
pt-snap query --template-info event
pt-snap capabilities --json
pt-snap overview "<db_path>" --json
```

Stop on invalid database metadata/schema or a missing required template, and
report the exact failure. A compatible legacy database may report metadata as
unavailable; record that provenance limitation rather than treating it as
import metadata. Do not replace a missing required template with raw SQL.

Before using the optional attribution phase, also verify its surfaces:
Reuse complete successful results from this conversation only for the same
CLI/Python environment and unchanged database target. Check CLI version and the
overview's resolved absolute database path. Summaries, truncated output, changed
environment/version or database, and unknown result identity require refreshing
the affected probe. Revalidate the contents even when reusing results.

Read `overview.import_metadata.status` (the `import_metadata` field in the
overview JSON), not just exit code 0 or outer `ok: true`. Stop on `invalid`
metadata or schema errors. Continue with `available`, or with legacy
`unavailable` and reason `metadata_missing` after recording unknown import
provenance. Stop on any other status/reason or incomplete result. Validate the
selected device against overview's devices and record its trace bounds.

Confirm these templates exist in the capabilities catalog before diagnosis:
`memory_peak`, `allocator_gap`, `allocation`, `event`. Read parameters,
`output_schema`, and field semantics from those entries. Stop on a missing
required template or failed probe and report the exact failure.
Do not replace a missing required template with raw SQL. Do not probe templates
one-by-one with `--template-info` or re-emit a reused catalog.

Prerequisite probe budget: 2 calls from cold, 1 with one reusable result, 0 with
both. Record tool-call count and output bytes separately; fewer calls need not
mean fewer bytes. Availability/focus/report-help checks are outside this budget.
Missing-focus recovery is the metadata-first exception: after user confirmation,
run metadata and apply its stop/legacy rules above, then obtain/reuse capabilities
and overview. Metadata alone does not replace overview; never reuse the missing
target's overview or device.

Before using the optional attribution phase, also verify
`active_memory_callstack_at_event` in the retained capabilities catalog; stop
that phase and report the missing template if absent. If using the report,
verify its command options with:

```bash
pt-snap query --template-info active_memory_callstack_at_event
pt-snap report peak-memory --help
```

Capabilities does not describe report command options, so keep this help check.
Stop the report phase and report the exact failure if it fails or the options
used below are absent. A complete successful help result from the same
CLI/Python environment and version may be reused.

## Diagnostic Workflow

### 1. Establish separate peaks and same-event gaps
Expand Down
30 changes: 24 additions & 6 deletions skills/pt-snap-memory-leak/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,18 +67,36 @@ Enter this recovery branch only when diagnosis depends on the current effective

### 3. Verify capabilities and the database in two calls

Run:
Apply the shared diagnostic preflight contract in `pt-snap-helper`, even on
direct invocation. Run only the probes whose complete results are not reusable:

```bash
pt-snap capabilities --json
pt-snap overview '<db_path>' --json
```

`capabilities --json` is the catalog: CLI version, every template contract (parameters, `output_schema`, field semantics), and the skill list. Do not probe templates one-by-one with `--template-info`.

`overview --json` is the read-only database orientation: device list, per-device first/last event id, and import-metadata status. Do not persist focus.

Prerequisite probe budget: previously 7 calls (`metadata` plus six `--template-info` probes). Now 2 calls (`capabilities` + `overview`). Record that reduction when evaluating this skill.
Reuse complete successful results from this conversation only for the same
CLI/Python environment and unchanged database target. Check CLI version and the
overview's resolved absolute database path. Summaries, truncated output, changed
environment/version or database, and unknown result identity require refreshing
the affected probe. Revalidate the contents even when reusing results.

`capabilities --json` is the catalog: CLI version, every template contract (parameters, `output_schema`, field semantics), and the skill list. Do not probe templates one-by-one with `--template-info`. Do not re-emit a reused catalog.

Read `overview.import_metadata.status` (the `import_metadata` field in the
overview JSON), not just exit code 0 or outer `ok: true`. Stop on `invalid`
metadata or schema errors. Continue with `available`, or with legacy
`unavailable` and reason `metadata_missing` after recording unknown import
provenance. Stop on any other status/reason or incomplete result. Validate the
selected device against overview's devices and record its trace bounds.

Prerequisite probe budget: 2 calls from cold, 1 with one reusable result, 0 with
both. Record tool-call count and output bytes separately; fewer calls need not
mean fewer bytes. Availability/focus checks are outside this discovery budget.
Missing-focus recovery is the metadata-first exception: after user confirmation,
run metadata and apply its stop/legacy rules above, then obtain/reuse capabilities
and overview. Metadata alone does not replace overview; never reuse the missing
target's overview or device.

Confirm these templates exist in the capabilities catalog before diagnosis: `memory_peak`, `allocator_gap`, `event`, `block`, `leak_detection`, `active_memory_callstack_at_event`, `preexisting_live`, `freed_block_lifetime`. If the catalog or overview fails, stop and report the exact failure. Do not silently substitute raw SQL for a missing core template.

Expand Down
58 changes: 39 additions & 19 deletions skills/pt-snap-memory-peak-breakdown/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -108,36 +108,56 @@ explicit path and do not enter this branch.
reason `metadata_missing`; record unknown import provenance and do not force
a re-import. Stop on schema errors or invalid metadata.

### 3. Verify SnapshotDB metadata
### 3. Verify capabilities and the database in two calls

Run with the resolved absolute database path:
Apply the shared diagnostic preflight contract in `pt-snap-helper`, even on
direct invocation. Run only the probes whose complete results are not reusable:

```bash
pt-snap metadata "<DB>" --json
pt-snap capabilities --json
pt-snap overview "<DB>" --json
```

Stop if the command rejects the database schema or reports invalid metadata. A
status of `unavailable` can represent a schema-valid legacy SnapshotDB; proceed
only after recording import provenance as unknown. Do not search for a source
pickle.

### 4. Verify the report command and required templates
Reuse complete successful results from this conversation only for the same
CLI/Python environment and unchanged database target. Check CLI version and the
overview's resolved absolute database path. Summaries, truncated output, changed
environment/version or database, and unknown result identity require refreshing
the affected probe. Revalidate the contents even when reusing results.

Read `overview.import_metadata.status` (the `import_metadata` field in the
overview JSON), not just exit code 0 or outer `ok: true`. Stop on `invalid`
metadata or schema errors. Continue with `available`, or with legacy
`unavailable` and reason `metadata_missing` after recording unknown import
provenance. Stop on any other status/reason or incomplete result. Validate the
selected device against overview's devices and record its trace bounds.

Confirm these templates exist in the capabilities catalog before diagnosis:
`memory_peak`, `allocator_gap`, `active_memory_callstack_at_event`,
`active_blocks_at_event`. Read parameters, `output_schema`, and field semantics
from those entries. Stop on a missing required template or failed probe and
report the exact failure. Do not substitute raw SQL. Do not probe templates
one-by-one with `--template-info` or re-emit a reused catalog.

Prerequisite probe budget: 2 calls from cold, 1 with one reusable result, 0 with
both. Record tool-call count and output bytes separately; fewer calls need not
mean fewer bytes. Availability/focus/report-help checks are outside this budget.
Missing-focus recovery is the metadata-first exception: after user confirmation,
run metadata and apply its stop/legacy rules above, then obtain/reuse capabilities
and overview. Metadata alone does not replace overview; never reuse the missing
target's overview or device.

### 4. Verify the report command

Run:

```bash
pt-snap report peak-memory --help
pt-snap query --template-info memory_peak
pt-snap query --template-info allocator_gap
pt-snap query --template-info active_memory_callstack_at_event
pt-snap query --template-info active_blocks_at_event
```

Stop and report the missing command or template if any check fails. A missing
template prints an error but still exits with status 0, so never rely on exit
codes for these checks: each template check succeeds only when its output
contains the expected `Template: <name>` record. Do not replace the
productized workflow with ad hoc SQL.
Capabilities does not describe report command options, so keep this help check.
Stop and report the exact failure if it fails or the options used below are
absent. A complete successful help result from the same CLI/Python environment
and version may be reused.

## Full-Trace Workflow

Expand Down Expand Up @@ -229,7 +249,7 @@ their event ID carries the range selection forward.
- It does not assign reserved/cache bytes, allocator gaps, or inactive allocated
bytes to callstacks. A large gap is evidence of counter separation at one
event, not proof of fragmentation, caching policy, or an OOM cause.
- Interpret `percent_of_active_blocks` using `--template-info active_memory_callstack_at_event` (units, denominator, and limits). Do not infer a block-count share from the column name. State the `include_static` choice whenever percentages are reported.
- Interpret `percent_of_active_blocks` using the `active_memory_callstack_at_event` entry in the retained capabilities catalog (units, denominator, and limits). Do not infer a block-count share from the column name. State the `include_static` choice whenever percentages are reported.

### Static, preexisting, and dynamic memory

Expand Down
49 changes: 44 additions & 5 deletions src/pt_snap_cli/bundled_skills/pt-snap-helper/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -94,10 +94,42 @@ value; `--opt=value` and numeric tokens do not consume the next
argument). Text mode still writes `Error:` lines to stdout.

This skill itself does not run analysis queries. The diagnostic skills own
those commands. For an existing SnapshotDB, point the next skill at
`pt-snap capabilities --json` and `pt-snap overview '<db_path>' --json`
before diagnosis so it does not need per-template `--template-info` or a
separate metadata probe.
those commands and the shared preflight below, including when invoked directly.

### Shared diagnostic preflight contract

For an existing SnapshotDB, the normal prerequisite probes are
`pt-snap capabilities --json` and `pt-snap overview '<db_path>' --json`.
The complete `templates[]` catalog supplies the same parameters, `output_schema`,
and field semantics as per-template `--template-info`; check every template
required by the selected skill by name. Stop on a missing required template or
failed probe and report the exact failure; do not substitute raw SQL.

Read `overview.import_metadata.status` (the `import_metadata` field in the
overview JSON), not just exit code 0 or outer `ok: true`. Stop on `invalid`
metadata or schema errors. Continue with `available`, or with legacy
`unavailable` and reason `metadata_missing` after recording unknown import
provenance. Stop on any other status/reason or incomplete result. Overview also
provides devices and trace bounds; validate the selected device against it.

Reuse complete successful results already obtained in this conversation only
for the same CLI/Python environment and unchanged database target. Capabilities
must match the current CLI version; overview must match the resolved absolute
database path. A summary, truncated output, changed environment/version, changed
database, or unknown result identity is not reusable. Fetch only the missing or
stale result. Direct invocation of a diagnostic skill performs the same complete
validation; helper use is not a prerequisite. Do not re-emit a reused catalog or
repeat per-template probes. Normal discovery costs 2 calls from cold, 1 with one
reusable result, and 0 with both; measure tool-call count and output bytes
separately, since the full catalog can be larger than individual probes.

Capabilities does not describe report command options. Keep
`pt-snap report peak-memory --help` when the selected workflow requires report
validation (mandatory for peak breakdown, conditional for fragmentation).
Availability/focus/report-help checks are separate from the two discovery calls.
Missing-focus recovery below is the explicit metadata-first exception: after
user confirmation, inspect metadata first, then obtain/reuse capabilities and
overview and apply these same checks. Metadata alone does not replace overview.

## Routing matrix

Expand Down Expand Up @@ -131,7 +163,8 @@ A SnapshotDB is a pt-snap SQLite database (typically `.db`) with a
1. Confirm the goal is leak, peak, or fragmentation.
2. Tell the next skill to start with `pt-snap capabilities --json` and
`pt-snap overview '<db_path>' --json` (overview first, then diagnose).
Pass the database path and device if the user supplied them.
Pass the database path and device if the user supplied them, plus any complete
reusable results under the shared preflight contract above.
3. Hand off to the matching diagnostic skill. Do not run leak, peak, or
fragmentation query templates from this helper.
4. Do not run `pt-snap focus <database_path>` to persist a new focus from this
Expand Down Expand Up @@ -166,6 +199,12 @@ explicit path and do not enter this branch.
re-resolve device from the confirmed database. This helper must not run
metadata, query, import, or persist focus.

The diagnostic skill must stop on invalid metadata or schema errors in this
metadata-first exception. Legacy `unavailable` with reason `metadata_missing`
permits continuing with unknown import provenance recorded. Then apply the
shared capabilities/overview preflight; do not reuse the missing target's
overview or treat metadata as an overview substitute.

This helper may mention that `pt-snap overview '<db_path>' --json` and
`pt-snap capabilities --json` exist. Running those orientation commands
belongs to the diagnostic skill. Do not import pickle or persist focus.
Expand Down
Loading
Loading