Restructure fizzy skill for progressive context loading

[robinbrandt]

Summary

• Split the monolithic 1118-line SKILL.md into a lean 338-line core with two on-demand reference files
• Cuts always-loaded context by 67% (38.6KB → 12.9KB) without losing any content
• Rewrites "Agent Invariants" as "Key Behaviors" with explanations of why each rule matters
• Removes config details already covered by AGENTS.md

New structure

skills/fizzy/
├── SKILL.md (338 lines)              # Core: decision trees, key behaviors, common workflows
└── references/
    ├── commands.md (370 lines)       # Full command reference — loaded on demand
    └── schemas.md (234 lines)        # Resource schemas + jq patterns — loaded on demand

Methodology

Ran 3 eval prompts (card creation with steps, filtered search with jq, webhook setup) against both the old monolithic skill and the new restructured skill, each producing CLI command plans graded against 20 assertions.

Results: 100% pass rate for both versions — identical correctness. The restructured skill was ~26% faster on average (32.7s vs 44.2s) due to smaller initial context. Token usage was roughly equivalent (~23K), confirming that on-demand reference reads don't add meaningful overhead.

Eval workspace with full results, grading, and timing data is available locally in skills/fizzy-workspace/ (not included in this PR).

Test plan

• Verify skill triggers correctly for common prompts (e.g., "create a card", "search fizzy")
• Verify reference files are consulted when detailed flags or schemas are needed
• Verify no content was lost in the restructure

🤖 Generated with Claude Code

---

Summary by cubic

Restructures the Fizzy skill to load a small core by default and pull detailed references on demand, cutting always-loaded context by 67% and improving planning speed ~26% with no loss of coverage.

• Refactors
  • Split skills/fizzy/SKILL.md into a lean core (338 lines) plus references/commands.md and references/schemas.md loaded only when needed.
  • Reduced always-loaded context from 38.6KB to 12.9KB; old content preserved across the two references.
  • Rewrote “Agent Invariants” as “Key Behaviors” with concise reasons (card number vs ID, jq usage, breadcrumbs, board context, rich text, new-signup welcome message).
  • Removed config details duplicated by AGENTS.md; kept essential setup/auth and context checks.
  • Kept functional parity: 3 evals showed 100% pass rate; average runtime ~32.7s vs 44.2s; token usage roughly the same.

^{Written for commit 2ce3a75. Summary will update on new commits.}

[cubic-dev-ai]

3 issues found across 3 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="skills/fizzy/references/commands.md">

<violation number="1" location="skills/fizzy/references/commands.md:336">
P2: File upload docs use conflicting response schemas (top-level vs `.data.*`), which can break jq-based command examples.</violation>
</file>

<file name="skills/fizzy/SKILL.md">

<violation number="1" location="skills/fizzy/SKILL.md:111">
P2: Quick Reference now omits required arguments for several commands, causing non-runnable command forms that can lead to CLI usage errors.</violation>

<violation number="2" location="skills/fizzy/SKILL.md:193">
P2: Response schema incorrectly implies `data` is always an object, but list responses use arrays, creating inconsistent docs that can lead to wrong jq parsing.</violation>
</file>

---

Since this is your first cubic review, here's how it works:

• cubic automatically reviews your code and comments on bugs and improvements
• Teach cubic by replying to its comments. cubic learns from your replies and gets better over time
• Add one-off context when rerunning by tagging @cubic-dev-ai with guidance or docs links (including llms.txt)
• Ask questions if you need clarification on any suggestion

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

P2: File upload docs use conflicting response schemas (top-level vs .data.*), which can break jq-based command examples.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At skills/fizzy/references/commands.md, line 336:

<comment>File upload docs use conflicting response schemas (top-level vs `.data.*`), which can break jq-based command examples.</comment>

<file context>
@@ -0,0 +1,370 @@
+
+```bash
+fizzy upload file PATH
+# Returns: { "signed_id": "...", "attachable_sgid": "..." }
+```
+
</file context>

[cubic-dev-ai]

P2: Quick Reference now omits required arguments for several commands, causing non-runnable command forms that can lead to CLI usage errors.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At skills/fizzy/SKILL.md, line 111:

<comment>Quick Reference now omits required arguments for several commands, causing non-runnable command forms that can lead to CLI usage errors.</comment>

<file context>
@@ -98,19 +107,21 @@ Want to change something?
-| board | `board list` | `board show ID` | `board create` | `board update ID` | `board delete ID` | `board publish ID`, `board unpublish ID`, `board entropy ID`, `board closed`, `board postponed`, `board stream`, `board involvement ID`, `migrate board ID` |
-| card | `card list` | `card show NUMBER` | `card create` | `card update NUMBER` | `card delete NUMBER` | `card move NUMBER`, `card publish NUMBER`, `card mark-read NUMBER`, `card mark-unread NUMBER` |
+| account | - | `account show` | - | `account settings-update` | - | `account entropy`, `account export-create/show`, `account join-code-show/reset/update` |
+| board | `board list` | `board show ID` | `board create` | `board update ID` | `board delete ID` | `board publish/unpublish`, `board entropy`, `board closed/postponed/stream`, `board involvement`, `migrate board` |
+| card | `card list` | `card show NUMBER` | `card create` | `card update NUMBER` | `card delete NUMBER` | `card move`, `card close/reopen/postpone/untriage`, `card assign/self-assign`, `card tag`, `card pin/unpin`, `card golden/ungolden`, `card watch/unwatch`, `card publish`, `card mark-read/mark-unread`, `card image-remove`, `card attachments` |
 | search | `search QUERY` | - | - | - | - | - |
</file context>

[cubic-dev-ai]

P2: Response schema incorrectly implies data is always an object, but list responses use arrays, creating inconsistent docs that can lead to wrong jq parsing.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At skills/fizzy/SKILL.md, line 193:

<comment>Response schema incorrectly implies `data` is always an object, but list responses use arrays, creating inconsistent docs that can lead to wrong jq parsing.</comment>

<file context>
@@ -137,655 +148,115 @@ Output format defaults to auto-detection: styled for TTY, JSON for pipes/non-TTY
-      "next_url": "https://..."
-    }
-  }
+  "data": { ... },
+  "summary": "4 boards",
+  "breadcrumbs": [ ... ],
</file context>

[robinbrandt]

Oops - this was not supposed to be posted already...