Skip to content

Commit 4ed699f

Browse files
committed
docs(skills): sync the projection-budget cards to the new error and note
Two cards quoted behaviour this branch changes. incident.md reproduced the old flat error string verbatim ("request fewer rows or fields"), which no longer appears in the output, and described the list path as failing without naming anything — it now names the largest fields, like detail always has. Both incident.md and alert.md also documented the "..." marker as the only sign that a value was shortened. That is what made the marker a trap: it is visible when you read a row, not when you filter one. Say that the stderr note exists and name what it is for.
1 parent 33c9c3e commit 4ed699f

2 files changed

Lines changed: 3 additions & 3 deletions

File tree

skills/flashduty/reference/alert.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@ fduty alert feed <alert-id> --output-format toon
3838
fduty alert-event list --channel <channel-id> --since 1h --limit 30 --output-format toon
3939
```
4040

41-
Structured `alert-event list` output stays below 16 KiB. A trailing `...` means a long retained string was shortened. In json/toon mode rows default to the compact projection `event_id,alert_id,event_severity,event_status,event_time,title` (a stderr note says so when it applies); any other response field is one `--fields` away — a key missing from the output means it wasn't selected, not that the server omits it.
41+
Structured `alert-event list` output stays below 16 KiB. A trailing `...` means a long retained string was shortened, and a stderr note names the clipped fields — heed it before matching on those values, because the clipped text is what a `jq` filter sees. In json/toon mode rows default to the compact projection `event_id,alert_id,event_severity,event_status,event_time,title` (a stderr note says so when it applies); any other response field is one `--fields` away — a key missing from the output means it wasn't selected, not that the server omits it.
4242

4343
## Hot flow — merge noisy alerts into an existing incident
4444

skills/flashduty/reference/incident.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -74,11 +74,11 @@ fduty incident comment "$ID" --comment-file "$COMMENT_FILE"
7474
fduty incident resolve <incident-id> --root-cause "DB primary failover delay" --resolution "Failover completed; latency normal."
7575
```
7676

77-
Projected `similar` lists stay below 16 KiB; a trailing `...` in a list row means a long retained string was shortened. `detail --fields` is different: it never shortens values — the projection must fit within 8 KiB as requested or the command fails and names the largest fields, so drop some fields (or drop `--fields` for the full unbounded detail) and retry.
77+
Projected `similar` lists stay below 16 KiB; a trailing `...` in a list row means a long retained string was shortened, and a stderr note names the fields that were clipped. `detail --fields` is different: it never shortens values — the projection must fit within 8 KiB as requested or the command fails and names the largest fields, so drop some fields (or drop `--fields` for the full unbounded detail) and retry.
7878

7979
`comment` never accepts the text as a command-line argument — only `--comment-file <path>` (or `--comment-file -` to read stdin), so backticks/`$()`/quotes inside the comment are inert. The command also reads back every target's timeline after writing and exits non-zero unless it finds an entry matching what it sent, so `Commented on ...` is proof of content fidelity, not just acceptance — no separate manual read-back is needed. Leading and trailing whitespace is stripped before sending (the server strips it too, so this is what gets stored); everything else, including interior blank lines, is preserved exactly.
8080

81-
> `incident list --output-format json|toon` defaults to the compact row projection `incident_id,title,incident_severity,progress,start_time,channel_id`. Pass `--fields incident_id,title,channel_id,start_time` when you need different list columns; use `incident detail <id>` / `incident get <id>` for full incident records. Any list-response field — including `labels` — is selectable this way (a key missing from the output means it wasn't selected, NOT that the server omits it; the command prints a stderr note when the default projection applies). The one exception is `alerts`: neither list nor detail responses ever fill it — use `incident alerts <id>` for an incident's alerts. Wide fields over many rows can exceed the 16 KiB structured-output bound and the command errors with "request fewer rows or fields" — lower `--limit`/page through, or use `insight` aggregates for distributions instead of dumping labels row by row.
81+
> `incident list --output-format json|toon` defaults to the compact row projection `incident_id,title,incident_severity,progress,start_time,channel_id`. Pass `--fields incident_id,title,channel_id,start_time` when you need different list columns; use `incident detail <id>` / `incident get <id>` for full incident records. Any list-response field — including `labels` — is selectable this way (a key missing from the output means it wasn't selected, NOT that the server omits it; the command prints a stderr note when the default projection applies). The one exception is `alerts`: neither list nor detail responses ever fill it — use `incident alerts <id>` for an incident's alerts. Wide fields over many rows can exceed the 16 KiB structured-output bound; the command then errors and names the largest fields by aggregate size, so lower `--limit`, drop the field it names, or use `insight` aggregates for distributions instead of dumping labels row by row. Before it errors it tries to fit the rows by shortening long string values — when it does, a stderr note says how many values were clipped and in which fields.
8282

8383
## Hot flow — full fault analysis (read-only summary)
8484

0 commit comments

Comments
 (0)