@oriro/orirocli 0.1.9 → 0.1.11

package/skills/craft/vercel-optimize/references/recommendations.md

@@ -1,214 +1,214 @@
-# Recommendations
-
-How recommendations are shaped, written, sanitized, and graded.
-
-## Table of contents
-
-- [Schema](#schema)
-- [Writing rules](#writing-rules)
-- [The 12 sanitizers](#the-12-sanitizers)
-- [Envelope-unwrap recovery](#envelope-unwrap-recovery)
-- [Grading rubric](#grading-rubric)
-- [Next.js version awareness](#nextjs-version-awareness)
-
-## Schema
-
-Every recommendation is a JSON object matching this TypeScript shape:
-
-```ts
-interface Recommendation {
-  // Customer-facing
-  what: string; // 1 line, lead with impact. Max 80 chars when feasible.
-  why: string; // 1-2 sentences. Root cause. Cites codebase findings + counts.
-  fix: string; // Step-by-step. Includes before/after code fences. Specific enough to implement.
-  bucket: "cost" | "performance" | "reliability";
-  effort: "low" | "medium" | "high";
-  affectedFiles: string[]; // Verified file paths, from candidate.files
-  currentBehavior: string; // What the code does now (with snippet)
-  desiredBehavior: string; // Target state (with snippet)
-  risk?: string; // Optional: e.g., "Removing force-dynamic may serve stale data on /admin"
-  verify: string; // How to confirm the fix worked. e.g., "Re-run `vercel metrics …` and watch p95"
-
-  // Impact (computed from impact-magnitude.mjs in Step 4)
-  impactLabel: {
-    performance?: string; // PRECISE: "Reduce /api/products p95 from 850ms toward ~250-400ms"
-    costMagnitude?: "negligible" | "small" | "medium" | "large" | "very-large";
-    costPhrase?: string; // "hundreds of dollars per month at current traffic"
-    billingDimension?: string;
-    fractionReduced?: number;
-  };
-  impactTier: "high" | "medium" | "low";
-  billingDimension?:
-    | "edge-requests"
-    | "function-duration"
-    | "image-optimization"
-    | "isr-reads"
-    | "isr-writes"
-    | "bandwidth"
-    | "data-cache-reads"
-    | "cron-invocations"
-    | string;
-
-  // Grounding
-  citations: string[]; // From references/docs-library.json allow-list. Required: ≥1 entry.
-  candidateRef?: string; // The gate candidate this rec traces to (e.g., "uncached_route:/api/products")
-  findingRefs?: string[]; // File:line markers from verifiedFindings.json
-  appliesAlsoTo?: Array<{
-    // Added by dedup when matching recs collapse into one customer-facing item.
-    candidateRef?: string;
-    affectedFiles?: string[];
-    o11ySignal?: string;
-    what?: string;
-  }>;
-  corroborationCount?: number; // Number of matching verified recs folded into this item, including itself.
-
-  // Verifier output (computed in Step 3.6)
-  verification?: {
-    passRate: number;
-    failed: Array<{ type: string; text: string; reason: string }>;
-  };
-
-  // Sanitizer audit trail (computed in Step 3.4)
-  sanitizerTrail?: string[]; // ["$-strip:2", "version-mismatch:next@15+:1", ...]
-  needsReview?: boolean; // Set when a sanitizer caught a hazard
-
-  // Grading (Step 3.5)
-  quality: {
-    specificity: number; // 0-1
-    actionability: number;
-    grounding: number;
-    evidence: number;
-    overall: number;
-    grade: "Excellent" | "Good" | "Fair" | "Poor";
-  };
-}
-```
-
-## Writing rules
-
-The recommender prompt explicitly tells the agent to follow these rules. Sanitizers enforce them after generation.
-
-**Voice and tone** are governed by [`references/voice.md`](./voice.md). Read it before writing recommendation prose; it keeps reports direct, metric-grounded, and free of internal process terms.
-
-### Lead with impact
-
-The `what` field opens with the verb + the change, not the framing. Compare:
-
-- ❌ "Consider enabling caching on the /api/products route" (filler before substance)
-- ✅ "Add Cache-Control with s-maxage to /api/products" (verb-first, scope-explicit)
-
-### Cite codebase findings with line numbers
-
-The `why` must reference a verified finding from `verifiedFindings.json`:
-
-- ❌ "The route is uncached" (could apply anywhere)
-- ✅ "src/app/api/products/route.ts:22 returns Response without Cache-Control; observability shows 0% cache hit on 1.2M invocations/mo"
-
-### No $ literals in customer fields
-
-The user-mandated rule. `what`/`why`/`fix`/`impact`/`currentBehavior`/`desiredBehavior` must not contain `$N` money literals. Use magnitude framing from `impact-magnitude.mjs`.
-
-- ❌ "Save $340/mo by adding s-maxage"
-- ✅ "Hundreds of dollars per month at current traffic"
-- ✅ (precise performance) "Move 1.2M monthly invocations to the CDN; expect p95 to drop from 850ms toward ~50ms on cache hits"
-
-The `$-strip` sanitizer enforces this at output time, but the prompt should also instruct the LLM not to emit dollar literals in the first place.
-
-### Before/after code fences required
-
-`currentBehavior` shows the offending snippet. `desiredBehavior` shows the target. Language-tagged code fences. Keep both under ~20 lines.
-
-### Cite at least one URL from the library
-
-`citations[]` must contain at least one entry from `references/docs-library.json`. The `missing-citation` sanitizer drops uncited recs. The `unknown-citation` and `version-mismatch` sanitizers strip invalid citations.
-
-### Match the user's framework version
-
-Don't recommend `'use cache'` (Next 15+) to a Next 13 user. The recommender prompt receives only the citation subset valid for the user's stack — but the LLM can still hallucinate. The `version-mismatch` sanitizer catches stragglers.
-
-## The 12 sanitizers
-
-Each sanitizer records its action in `rec.sanitizerTrail` when it mutates a field. Tag format: `tag:detail`. Tags are lexically stable — downstream consumers grep them.
-
-| #   | Sanitizer                 | Trigger                                                | Action                                             | Trail tag                              |
-| --- | ------------------------- | ------------------------------------------------------ | -------------------------------------------------- | -------------------------------------- |
-| 1   | `$-strip`                 | Money-literal regex in customer field                  | Replace with "the billed cost"                     | `$-strip:N`                            |
-| 2   | `vercel-directive-strip`  | `stale-if-error` / `proxy-revalidate` in cache-control | Strip directive (Vercel CDN doesn't honor)         | `vercel-directive-strip:directive`     |
-| 3   | `rate-limit`              | Concurrency × delay > known provider rate limit        | Prepend caveat, set needsReview                    | `rate-limit:provider:prescribed/limit` |
-| 4   | `pre-release`             | Fix enables `-rc`/`-beta`/`-canary` feature            | Append "requires pre-release version" caveat       | `pre-release:pkg@version`              |
-| 5   | `middleware-conflict`     | Rec targets route covered by middleware matcher        | Append "Middleware {matcher} may intercept" caveat | `middleware-conflict:matcher`          |
-| 6   | `undeclared-dep`          | Fix imports a package not in package.json              | Prepend "Add dependency first: npm i {pkg}"        | `undeclared-dep:pkg`                   |
-| 7   | `count-correct`           | Cited count > verified count, ground-truth known       | Rewrite to "~N" with verified count                | `count-correct:token:cited→actual`     |
-| 8   | `count-strip`             | Cited count > verified count, no ground truth          | Rewrite to "a number of"                           | `count-strip:token`                    |
-| 9   | `rendering-mode-mislabel` | Rec blames ISR/SSR on a static page                    | Append warning, set needsReview                    | `rendering-mode-mislabel`              |
-| 10  | `unknown-citation`        | URL not in `references/docs-library.json`              | Strip URL, set needsReview if all stripped         | `unknown-citation:url`                 |
-| 11  | `version-mismatch`        | URL's `applicableFrameworks` doesn't match stack       | Strip URL, set needsReview if all stripped         | `version-mismatch:url`                 |
-| 12  | `missing-citation`        | `citations.length === 0` after other sanitizers        | DROP rec entirely                                  | (rec not emitted; counted at end)      |
-
-The sanitizer order matters: dollar-strip runs first (cheap, deterministic), then content sanitizers, then citation sanitizers last. This guarantees citation count is computed against the final state.
-
-The `recordSanitizer(rec, tag)` helper is the single entry point — sanitizers MUST call it before mutating fields. Otherwise the audit trail rots.
-
-### Provider rate limits
-
-Used by sanitizer #3. These provider limits are public contract values:
-
-| Provider  | Limit   | Doc URL                                                |
-| --------- | ------- | ------------------------------------------------------ |
-| Notion    | 3 rps   | https://developers.notion.com/reference/request-limits |
-| OpenAI    | 30 rps  | https://platform.openai.com/docs/guides/rate-limits    |
-| Stripe    | 100 rps | https://docs.stripe.com/rate-limits                    |
-| Anthropic | 10 rps  | https://docs.anthropic.com/en/api/rate-limits          |
-
-Tiers/plans differ; these are first-tier defaults. The sanitizer prepends a caveat if the rec prescribes higher concurrency.
-
-## Envelope-unwrap recovery
-
-Not a sanitizer — a recovery step. LLMs occasionally wrap their JSON output in an envelope:
-
-```json
-{ "data": { "recommendations": [...] } }
-{ "result": { "recommendations": [...] } }
-{ "insights": { "recommendations": [...] } }
-```
-
-`attemptManualRecovery` peels one wrapping layer before schema validation. Increments `hygieneCounters.envelopeUnwraps`. Logs the unwrap to the run log.
-
-This is the only "creative" parsing the skill does. Anything else that fails schema validation is rejected.
-
-## Grading rubric
-
-Each rec is scored on four axes, 0-1 each. Average → grade:
-
-| Axis          | What it measures                            | Strong (1.0) signal                                                                        |
-| ------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------ |
-| Specificity   | Concrete files, line numbers, code snippets | Triple-backtick code fence OR inline code ≥10 chars + verified file path                   |
-| Actionability | Clear "do this then that" steps             | Numbered steps; verbs present in each step; no "consider"/"might"                          |
-| Grounding     | Claims trace to findings or metric data     | `sourceIndex` matches a finding OR rec has affectedFiles + code fences (presumed evidence) |
-| Evidence      | Numeric, observed claims                    | Count words (errors, queries, invocations) + units (% / ms / s / K / M)                    |
-
-Grade thresholds:
-
-- `Excellent` ≥ 0.85
-- `Good` 0.70 – 0.85
-- `Fair` 0.55 – 0.70
-- `Poor` < 0.55 → dropped at quality floor in Step 4
-
-## Next.js version awareness
-
-The recommender's citation library is filtered by `signals.json.stack.framework@frameworkVersion`. The agent should still self-check the version when picking which APIs to recommend:
-
-| Feature                            | Available   | Notes                                          |
-| ---------------------------------- | ----------- | ---------------------------------------------- |
-| App Router                         | Next ≥ 13.0 | Default since 14                               |
-| `generateStaticParams`             | Next ≥ 13.0 | Replaces getStaticPaths for App Router         |
-| Fetch `next: { revalidate }`       | Next ≥ 13.0 | Note: default fetch caching flipped in Next 15 |
-| `unstable_cache`                   | Next 14-15  | Replaced by 'use cache' in 16                  |
-| `'use cache'` directive            | Next ≥ 15.0 | Persistent cache primitive                     |
-| `cacheLife()`, `cacheTag()`        | Next ≥ 15.0 | Pairs with 'use cache'                         |
-| `after()`                          | Next ≥ 15.0 | Non-blocking post-response work                |
-| Partial Prerendering               | Next ≥ 15.0 | Stable target later — verify per release       |
-| `revalidateTag` / `revalidatePath` | Next ≥ 13.4 | Tag-based on-demand invalidation               |
-| `cookies()` / `headers()` async    | Next ≥ 15.0 | Async pattern in 15+                           |
-
-The skill's curated citation library encodes these constraints via `applicableFrameworks`. If a contributor adds a new Next.js feature URL, they MUST set the right semver range in `references/docs-library.json`.
+# Recommendations
+
+How recommendations are shaped, written, sanitized, and graded.
+
+## Table of contents
+
+- [Schema](#schema)
+- [Writing rules](#writing-rules)
+- [The 12 sanitizers](#the-12-sanitizers)
+- [Envelope-unwrap recovery](#envelope-unwrap-recovery)
+- [Grading rubric](#grading-rubric)
+- [Next.js version awareness](#nextjs-version-awareness)
+
+## Schema
+
+Every recommendation is a JSON object matching this TypeScript shape:
+
+```ts
+interface Recommendation {
+  // Customer-facing
+  what: string; // 1 line, lead with impact. Max 80 chars when feasible.
+  why: string; // 1-2 sentences. Root cause. Cites codebase findings + counts.
+  fix: string; // Step-by-step. Includes before/after code fences. Specific enough to implement.
+  bucket: "cost" | "performance" | "reliability";
+  effort: "low" | "medium" | "high";
+  affectedFiles: string[]; // Verified file paths, from candidate.files
+  currentBehavior: string; // What the code does now (with snippet)
+  desiredBehavior: string; // Target state (with snippet)
+  risk?: string; // Optional: e.g., "Removing force-dynamic may serve stale data on /admin"
+  verify: string; // How to confirm the fix worked. e.g., "Re-run `vercel metrics …` and watch p95"
+
+  // Impact (computed from impact-magnitude.mjs in Step 4)
+  impactLabel: {
+    performance?: string; // PRECISE: "Reduce /api/products p95 from 850ms toward ~250-400ms"
+    costMagnitude?: "negligible" | "small" | "medium" | "large" | "very-large";
+    costPhrase?: string; // "hundreds of dollars per month at current traffic"
+    billingDimension?: string;
+    fractionReduced?: number;
+  };
+  impactTier: "high" | "medium" | "low";
+  billingDimension?:
+    | "edge-requests"
+    | "function-duration"
+    | "image-optimization"
+    | "isr-reads"
+    | "isr-writes"
+    | "bandwidth"
+    | "data-cache-reads"
+    | "cron-invocations"
+    | string;
+
+  // Grounding
+  citations: string[]; // From references/docs-library.json allow-list. Required: ≥1 entry.
+  candidateRef?: string; // The gate candidate this rec traces to (e.g., "uncached_route:/api/products")
+  findingRefs?: string[]; // File:line markers from verifiedFindings.json
+  appliesAlsoTo?: Array<{
+    // Added by dedup when matching recs collapse into one customer-facing item.
+    candidateRef?: string;
+    affectedFiles?: string[];
+    o11ySignal?: string;
+    what?: string;
+  }>;
+  corroborationCount?: number; // Number of matching verified recs folded into this item, including itself.
+
+  // Verifier output (computed in Step 3.6)
+  verification?: {
+    passRate: number;
+    failed: Array<{ type: string; text: string; reason: string }>;
+  };
+
+  // Sanitizer audit trail (computed in Step 3.4)
+  sanitizerTrail?: string[]; // ["$-strip:2", "version-mismatch:next@15+:1", ...]
+  needsReview?: boolean; // Set when a sanitizer caught a hazard
+
+  // Grading (Step 3.5)
+  quality: {
+    specificity: number; // 0-1
+    actionability: number;
+    grounding: number;
+    evidence: number;
+    overall: number;
+    grade: "Excellent" | "Good" | "Fair" | "Poor";
+  };
+}
+```
+
+## Writing rules
+
+The recommender prompt explicitly tells the agent to follow these rules. Sanitizers enforce them after generation.
+
+**Voice and tone** are governed by [`references/voice.md`](./voice.md). Read it before writing recommendation prose; it keeps reports direct, metric-grounded, and free of internal process terms.
+
+### Lead with impact
+
+The `what` field opens with the verb + the change, not the framing. Compare:
+
+- ❌ "Consider enabling caching on the /api/products route" (filler before substance)
+- ✅ "Add Cache-Control with s-maxage to /api/products" (verb-first, scope-explicit)
+
+### Cite codebase findings with line numbers
+
+The `why` must reference a verified finding from `verifiedFindings.json`:
+
+- ❌ "The route is uncached" (could apply anywhere)
+- ✅ "src/app/api/products/route.ts:22 returns Response without Cache-Control; observability shows 0% cache hit on 1.2M invocations/mo"
+
+### No $ literals in customer fields
+
+The user-mandated rule. `what`/`why`/`fix`/`impact`/`currentBehavior`/`desiredBehavior` must not contain `$N` money literals. Use magnitude framing from `impact-magnitude.mjs`.
+
+- ❌ "Save $340/mo by adding s-maxage"
+- ✅ "Hundreds of dollars per month at current traffic"
+- ✅ (precise performance) "Move 1.2M monthly invocations to the CDN; expect p95 to drop from 850ms toward ~50ms on cache hits"
+
+The `$-strip` sanitizer enforces this at output time, but the prompt should also instruct the LLM not to emit dollar literals in the first place.
+
+### Before/after code fences required
+
+`currentBehavior` shows the offending snippet. `desiredBehavior` shows the target. Language-tagged code fences. Keep both under ~20 lines.
+
+### Cite at least one URL from the library
+
+`citations[]` must contain at least one entry from `references/docs-library.json`. The `missing-citation` sanitizer drops uncited recs. The `unknown-citation` and `version-mismatch` sanitizers strip invalid citations.
+
+### Match the user's framework version
+
+Don't recommend `'use cache'` (Next 15+) to a Next 13 user. The recommender prompt receives only the citation subset valid for the user's stack — but the LLM can still hallucinate. The `version-mismatch` sanitizer catches stragglers.
+
+## The 12 sanitizers
+
+Each sanitizer records its action in `rec.sanitizerTrail` when it mutates a field. Tag format: `tag:detail`. Tags are lexically stable — downstream consumers grep them.
+
+| #   | Sanitizer                 | Trigger                                                | Action                                             | Trail tag                              |
+| --- | ------------------------- | ------------------------------------------------------ | -------------------------------------------------- | -------------------------------------- |
+| 1   | `$-strip`                 | Money-literal regex in customer field                  | Replace with "the billed cost"                     | `$-strip:N`                            |
+| 2   | `vercel-directive-strip`  | `stale-if-error` / `proxy-revalidate` in cache-control | Strip directive (Vercel CDN doesn't honor)         | `vercel-directive-strip:directive`     |
+| 3   | `rate-limit`              | Concurrency × delay > known provider rate limit        | Prepend caveat, set needsReview                    | `rate-limit:provider:prescribed/limit` |
+| 4   | `pre-release`             | Fix enables `-rc`/`-beta`/`-canary` feature            | Append "requires pre-release version" caveat       | `pre-release:pkg@version`              |
+| 5   | `middleware-conflict`     | Rec targets route covered by middleware matcher        | Append "Middleware {matcher} may intercept" caveat | `middleware-conflict:matcher`          |
+| 6   | `undeclared-dep`          | Fix imports a package not in package.json              | Prepend "Add dependency first: npm i {pkg}"        | `undeclared-dep:pkg`                   |
+| 7   | `count-correct`           | Cited count > verified count, ground-truth known       | Rewrite to "~N" with verified count                | `count-correct:token:cited→actual`     |
+| 8   | `count-strip`             | Cited count > verified count, no ground truth          | Rewrite to "a number of"                           | `count-strip:token`                    |
+| 9   | `rendering-mode-mislabel` | Rec blames ISR/SSR on a static page                    | Append warning, set needsReview                    | `rendering-mode-mislabel`              |
+| 10  | `unknown-citation`        | URL not in `references/docs-library.json`              | Strip URL, set needsReview if all stripped         | `unknown-citation:url`                 |
+| 11  | `version-mismatch`        | URL's `applicableFrameworks` doesn't match stack       | Strip URL, set needsReview if all stripped         | `version-mismatch:url`                 |
+| 12  | `missing-citation`        | `citations.length === 0` after other sanitizers        | DROP rec entirely                                  | (rec not emitted; counted at end)      |
+
+The sanitizer order matters: dollar-strip runs first (cheap, deterministic), then content sanitizers, then citation sanitizers last. This guarantees citation count is computed against the final state.
+
+The `recordSanitizer(rec, tag)` helper is the single entry point — sanitizers MUST call it before mutating fields. Otherwise the audit trail rots.
+
+### Provider rate limits
+
+Used by sanitizer #3. These provider limits are public contract values:
+
+| Provider  | Limit   | Doc URL                                                |
+| --------- | ------- | ------------------------------------------------------ |
+| Notion    | 3 rps   | https://developers.notion.com/reference/request-limits |
+| OpenAI    | 30 rps  | https://platform.openai.com/docs/guides/rate-limits    |
+| Stripe    | 100 rps | https://docs.stripe.com/rate-limits                    |
+| Anthropic | 10 rps  | https://docs.anthropic.com/en/api/rate-limits          |
+
+Tiers/plans differ; these are first-tier defaults. The sanitizer prepends a caveat if the rec prescribes higher concurrency.
+
+## Envelope-unwrap recovery
+
+Not a sanitizer — a recovery step. LLMs occasionally wrap their JSON output in an envelope:
+
+```json
+{ "data": { "recommendations": [...] } }
+{ "result": { "recommendations": [...] } }
+{ "insights": { "recommendations": [...] } }
+```
+
+`attemptManualRecovery` peels one wrapping layer before schema validation. Increments `hygieneCounters.envelopeUnwraps`. Logs the unwrap to the run log.
+
+This is the only "creative" parsing the skill does. Anything else that fails schema validation is rejected.
+
+## Grading rubric
+
+Each rec is scored on four axes, 0-1 each. Average → grade:
+
+| Axis          | What it measures                            | Strong (1.0) signal                                                                        |
+| ------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| Specificity   | Concrete files, line numbers, code snippets | Triple-backtick code fence OR inline code ≥10 chars + verified file path                   |
+| Actionability | Clear "do this then that" steps             | Numbered steps; verbs present in each step; no "consider"/"might"                          |
+| Grounding     | Claims trace to findings or metric data     | `sourceIndex` matches a finding OR rec has affectedFiles + code fences (presumed evidence) |
+| Evidence      | Numeric, observed claims                    | Count words (errors, queries, invocations) + units (% / ms / s / K / M)                    |
+
+Grade thresholds:
+
+- `Excellent` ≥ 0.85
+- `Good` 0.70 – 0.85
+- `Fair` 0.55 – 0.70
+- `Poor` < 0.55 → dropped at quality floor in Step 4
+
+## Next.js version awareness
+
+The recommender's citation library is filtered by `signals.json.stack.framework@frameworkVersion`. The agent should still self-check the version when picking which APIs to recommend:
+
+| Feature                            | Available   | Notes                                          |
+| ---------------------------------- | ----------- | ---------------------------------------------- |
+| App Router                         | Next ≥ 13.0 | Default since 14                               |
+| `generateStaticParams`             | Next ≥ 13.0 | Replaces getStaticPaths for App Router         |
+| Fetch `next: { revalidate }`       | Next ≥ 13.0 | Note: default fetch caching flipped in Next 15 |
+| `unstable_cache`                   | Next 14-15  | Replaced by 'use cache' in 16                  |
+| `'use cache'` directive            | Next ≥ 15.0 | Persistent cache primitive                     |
+| `cacheLife()`, `cacheTag()`        | Next ≥ 15.0 | Pairs with 'use cache'                         |
+| `after()`                          | Next ≥ 15.0 | Non-blocking post-response work                |
+| Partial Prerendering               | Next ≥ 15.0 | Stable target later — verify per release       |
+| `revalidateTag` / `revalidatePath` | Next ≥ 13.4 | Tag-based on-demand invalidation               |
+| `cookies()` / `headers()` async    | Next ≥ 15.0 | Async pattern in 15+                           |
+
+The skill's curated citation library encodes these constraints via `applicableFrameworks`. If a contributor adds a new Next.js feature URL, they MUST set the right semver range in `references/docs-library.json`.