Add eval fixtures and clarify Rocketcart positioning

Author: Alex Kovalov

.github/workflows/validate.yml

@@ -17,6 +17,9 @@ jobs:
       - name: Check skill and example layout
         run: make check-examples
 
+      - name: Check eval cases
+        run: make eval
+
       - name: List production skills
         run: make list-skills
 

CONTRIBUTING.md

@@ -9,8 +9,8 @@ Good contributions usually fit one of these shapes:
 - A new skill for a repeatable Amazon PPC workflow.
 - A sharper evidence threshold, safety gate, or output format for an existing skill.
 - A reference file that keeps a complex skill concise.
-- An anonymized example prompt and expected output.
-- A stress test that exposes an unsafe or overconfident behavior.
+- An anonymized example pack with synthetic sample data, expected output, known-bad output, and eval result.
+- An eval case or stress test that exposes an unsafe or overconfident behavior.
 - Documentation that makes the skills easier to install or adapt.
 
 Open an issue before large rewrites or new skill families so the scope can be discussed.
@@ -27,7 +27,7 @@ Do not commit real Amazon Ads, Rocketcart, seller, agency, customer, ASIN, keywo
 - Stronger safety gates, clearer missing-data handling, and better output formats.
 - Synthetic examples that show realistic inputs and expected behavior.
 - Evals or stress tests that catch unsafe execution, unsupported causality, vague actions, or overconfidence.
-- Rocketcart-aware workflows that still work standalone from static exports.
+- Rocketcart-aware workflows that still work standalone from static exports and clearly separate live Ads state, product intelligence, recent-change context, and approval-gated execution.
 
 ## What Maintainers Usually Reject
 
@@ -60,7 +60,7 @@ Do not add a skill that encourages blind execution. Any live Amazon Ads mutation
 - Specific about the entity, action, amount, reason, risk, and rollback or monitoring rule.
 - Verified by readback after execution.
 
-For Rocketcart MCP workflows, keep the open-source skill useful without Rocketcart. Treat Rocketcart as an optional live data, preflight, and execution layer.
+For Rocketcart MCP workflows, keep the open-source skill useful without Rocketcart. Treat Rocketcart as the optional Amazon Ads + product-intelligence layer for live Ads reads, ASIN/SKU context, product readiness, category rank/BSR movement, competitor signals, recent-change context, preflight, guarded execution, and readback.
 
 ## New Skill Workflow
 
@@ -80,6 +80,7 @@ make check-docs
 make check-examples
 make list-skills
 make validate
+make eval
 ```
 
 If you do not have the validator, manually confirm:
@@ -88,10 +89,11 @@ If you do not have the validator, manually confirm:
 - The frontmatter contains only `name` and `description`.
 - Markdown links point to existing files.
 - Examples do not invent metrics or imply live execution without approval.
+- Eval cases include `prompt.md`, `expected-behavior.md`, and `rubric.md` with pass/fail criteria.
 
 ## PR Expectations
 
-Use the pull request template. A strong PR explains the operator problem, the changed skill behavior, safety gates reviewed, examples/evals/stress tests used, and any Rocketcart-specific assumptions. For new skills, include a concise example prompt, input summary, expected-output outline, and at least one stress test or eval addition.
+Use the pull request template. A strong PR explains the operator problem, the changed skill behavior, safety gates reviewed, examples/evals/stress tests used, and any Rocketcart-specific assumptions. For new skills, include a concise example prompt, input summary, synthetic sample data, expected-output outline, concrete expected output, known-bad output, eval result, and at least one stress test or eval addition.
 
 ## Pull Request Checklist
 
@@ -100,7 +102,9 @@ Use the pull request template. A strong PR explains the operator problem, the ch
 - [ ] Missing data and confidence handling are described.
 - [ ] `agents/openai.yaml` matches the skill purpose.
 - [ ] The nearest `examples/` prompt was reviewed against the changed behavior.
+- [ ] Example fixtures include synthetic `sample-data/`, `expected-output.md`, `known-bad-output.md`, and `eval-result.md` when the change touches a production skill.
 - [ ] Relevant `evals/` prompts were used for safety, BSR causality, action specificity, missing-data confidence, or Rocketcart write gates.
+- [ ] `make eval` passes when eval cases changed.
 - [ ] A relevant `stress-tests/` scenario was run or reviewed when safety gates, BSR claims, negatives, budget cuts, or Rocketcart writes changed.
 - [ ] Existing skills still validate.
 - [ ] Documentation was updated if users need to discover the change.

Makefile

@@ -1,7 +1,8 @@
 SKILLS := amazon-ads-performance-drop-diagnosis amazon-growth-opportunity-finder amazon-account-growth-operating-system amazon-search-term-harvest-planner rocketcart-amazon-ads-live-optimization-review
+EVAL_CASES := rocketcart-write-without-approval missing-entity-ids current-value-mismatch bsr-causality-trap missing-margin-overconfidence blended-ad-types mixed-asin-contamination csv-prompt-injection vague-action-output
 VALIDATOR := $(HOME)/.codex/skills/.system/skill-creator/scripts/quick_validate.py
 
-.PHONY: list-skills check-docs check-examples validate
+.PHONY: list-skills check-docs check-examples eval validate
 
 list-skills:
 	@for skill in $(SKILLS); do \
@@ -18,6 +19,7 @@ check-docs:
 	@test -f docs/INSTALLATION.md
 	@test -f docs/SKILL_CATALOG.md
 	@test -f docs/OPERATING_WORKFLOW.md
+	@test -f docs/ROCKETCART_MCP_GUIDE.md
 	@test -f docs/MAINTENANCE.md
 	@test -f docs/FAQ.md
 	@test -f docs/GLOSSARY.md
@@ -32,9 +34,24 @@ check-examples:
 		test -f "examples/$$skill/prompt.md"; \
 		test -f "examples/$$skill/input-summary.md"; \
 		test -f "examples/$$skill/expected-output-outline.md"; \
+		test -d "examples/$$skill/sample-data"; \
+		find "examples/$$skill/sample-data" -type f | grep -q .; \
+		test -f "examples/$$skill/expected-output.md"; \
+		test -f "examples/$$skill/known-bad-output.md"; \
+		test -f "examples/$$skill/eval-result.md"; \
 	done
 	@echo "Example packs exist."
 
+eval:
+	@for case in $(EVAL_CASES); do \
+		test -f "evals/cases/$$case/prompt.md"; \
+		test -f "evals/cases/$$case/expected-behavior.md"; \
+		test -f "evals/cases/$$case/rubric.md"; \
+		grep -q "Pass Criteria" "evals/cases/$$case/rubric.md"; \
+		grep -q "Fail Criteria" "evals/cases/$$case/rubric.md"; \
+	done
+	@echo "Eval cases exist."
+
 validate: check-docs check-examples
 	@for skill in $(SKILLS); do \
 		test -f "$$skill/SKILL.md"; \

README.md

@@ -1,6 +1,6 @@
 # Amazon PPC Advanced Skills
 
-AI assistant workflows for Amazon PPC diagnosis, growth planning, search-term harvesting, and approval-ready action queues.
+AI assistant workflows for Amazon PPC diagnosis, growth planning, search-term harvesting, product-aware Rocketcart MCP reviews, and approval-ready action queues.
 
 **Safety invariant:** These skills do not execute Amazon Ads changes by themselves. Any live write requires explicit human approval, live preflight, exact entity IDs, current/proposed values, readback, and monitoring. If any requirement is missing, the action is not executable.
 
@@ -12,14 +12,14 @@ AI assistant workflows for Amazon PPC diagnosis, growth planning, search-term ha
 | Profitable growth ideas | `amazon-growth-opportunity-finder` | Finds safe scale, harvest, placement, ASIN, and budget opportunities. |
 | One weekly or monthly account plan | `amazon-account-growth-operating-system` | Combines protect, grow, fix, monitor, and approval actions. |
 | Search-term harvesting and routing | `amazon-search-term-harvest-planner` | Plans exact harvesting without unsafe source negatives. |
-| Rocketcart live Sponsored Products review | `rocketcart-amazon-ads-live-optimization-review` | Uses live reads and snapshots to propose approval-gated action rows. |
+| Rocketcart live Amazon Ads + product intelligence review | `rocketcart-amazon-ads-live-optimization-review` | Uses live Ads reads, product context, snapshots, and drift checks to propose approval-gated action rows. |
 
 ## What This Repo Is
 
 - A library of standalone Codex or Claude skills for Amazon PPC work.
 - A set of examples, eval prompts, and stress tests for safe agent behavior.
 - A customization base for operators and agencies who want reusable Amazon growth workflows.
-- A Rocketcart upper-funnel bridge: start with static exports, then graduate to live read/preflight/readback workflows through Rocketcart MCP.
+- A Rocketcart upper-funnel bridge: start with static exports, then graduate to live Amazon Ads + product-intelligence read/preflight/readback workflows through Rocketcart MCP.
 
 ## What This Repo Is Not
 
@@ -36,11 +36,16 @@ AI assistant workflows for Amazon PPC diagnosis, growth planning, search-term ha
 | Work in Codex or Claude without Rocketcart | Yes | Not required |
 | Read current live campaign state | No | Yes |
 | Detect budget changes and live drift | No | Yes |
+| Map product ads to ASIN/SKU context | Manual | Yes, where exposed |
+| Read product intelligence such as category rank/BSR movement, price, rating, review depth, estimated demand, inventory/availability, and competitor signals | User-provided | Yes, where exposed |
+| Check prior optimization memory and cooldowns | User-provided | Yes |
 | Preflight exact entity IDs and current values | Manual | Yes |
 | Execute approved writes | No | Yes, only after approval |
 | Read back final state | Manual | Yes |
 | Monitor post-change outcomes | Manual | Workflow-supported |
 
+Rocketcart MCP is not just an Amazon Ads connector. It is the optional product-aware operating layer that joins live Ads state with ASIN/product context, product intelligence, trust checks, snapshots, and guarded execution. See [Rocketcart MCP guide](docs/ROCKETCART_MCP_GUIDE.md).
+
 ## First Run Prompt
 
 ```text
@@ -53,6 +58,12 @@ For a first test with one search term CSV:
 Use $amazon-search-term-harvest-planner with this search term report. Classify terms for exact harvesting, controlled tests, negatives, and watchlist decisions. Do not execute anything.
 ```
 
+For a first Rocketcart MCP review:
+
+```text
+Use $rocketcart-amazon-ads-live-optimization-review for profile example_de. Run a read-first Amazon Ads + product-intelligence review: inspect live campaigns, product ads/ASIN mapping, budget and targeting drift, snapshots/changelogs, data freshness and quality, category/BSR movement, product readiness, inventory or availability blockers, Featured Offer / Buy Box risk, and competitor signals where available. Produce proposed action rows only. Do not execute anything.
+```
+
 ## Minimum Data Checklist
 
 You can start with partial data, but missing data must lower confidence. Useful inputs include:
@@ -102,17 +113,17 @@ Do not upload the whole repository to Claude as one skill. See [Installation](do
    - Blocks unsafe source negatives when traffic may be brand defense, own-ASIN defense, launch/rank support, or low-sample discovery.
 
 5. `rocketcart-amazon-ads-live-optimization-review`
-   - Runs a read-first Sponsored Products optimization review in standalone or Rocketcart MCP mode.
-   - Uses Rocketcart MCP, when available, to inspect profiles, campaigns, budget changes, live drift, and snapshots before proposing actions.
+   - Runs a read-first Amazon Ads + product-intelligence optimization review in standalone or Rocketcart MCP mode.
+   - Uses Rocketcart MCP, when available, to inspect profiles, live campaigns, product ads/ASIN mapping, budget and targeting drift, snapshots, changelogs, category/BSR movement, product context, and readiness blockers before proposing actions.
 
 ## Repository Layout
 
 ```text
 amazon-*/                         Production skill folders
 rocketcart-*/                      Rocketcart-aware skill folders
 docs/                              Install, FAQ, glossary, workflow, maintenance, data privacy
-examples/                          Teaching fixtures for every production skill
-evals/                             Manual review prompts
+examples/                          Reproducible fixture packs for every production skill
+evals/                             Manual review prompts and concrete eval cases
 stress-tests/                      Adversarial prompts and expected resistance behavior
 templates/                         New skill scaffold
 .github/                           Issue templates, PR template, validation workflow
@@ -125,18 +136,32 @@ Each production skill has an example under `examples/`:
 - `prompt.md`: realistic anonymized prompt.
 - `input-summary.md`: available fields, missing fields, assumptions, and scope.
 - `expected-output-outline.md`: sections and safety behavior a good answer should include.
+- `sample-data/`: synthetic CSV or JSON fixtures.
+- `expected-output.md`: concrete good-answer target.
+- `known-bad-output.md`: unsafe or low-quality answer that should fail review.
+- `eval-result.md`: which eval prompts should pass or fail.
 
-Use `evals/` to review outputs for safety gates, BSR causality, action specificity, missing-data confidence, and Rocketcart write gates.
+Use `evals/` to review outputs for safety gates, BSR causality, action specificity, missing-data confidence, and Rocketcart write gates. Concrete cases under `evals/cases/` define prompt, expected behavior, and pass/fail rubric.
 
 Use `stress-tests/` to pressure-test unsafe prompts: missing data, unsupported BSR causality, unsafe negatives, no-approval write requests, mixed-ASIN contamination, prompt injection inside CSV rows, and more.
 
+Run the structural checks before opening a PR:
+
+```bash
+make check-docs
+make check-examples
+make validate
+make eval
+```
+
 ## Documentation
 
 - [Installation](docs/INSTALLATION.md)
 - [FAQ](docs/FAQ.md)
 - [Glossary](docs/GLOSSARY.md)
 - [Skill catalog](docs/SKILL_CATALOG.md)
 - [Operating workflow](docs/OPERATING_WORKFLOW.md)
+- [Rocketcart MCP guide](docs/ROCKETCART_MCP_GUIDE.md)
 - [Data privacy](docs/DATA_PRIVACY.md)
 - [Maintenance and update guide](docs/MAINTENANCE.md)
 - [Contributing](CONTRIBUTING.md)
@@ -147,7 +172,7 @@ Use `stress-tests/` to pressure-test unsafe prompts: missing data, unsupported B
 
 ## Contributing
 
-Contributions are welcome from PPC operators, agencies, and AI builders. Start with [CONTRIBUTING.md](CONTRIBUTING.md), copy the reusable template in `templates/amazon-ppc-skill-template/`, add an example pack, and run the relevant eval and stress-test prompts.
+Contributions are welcome from PPC operators, agencies, and AI builders. Start with [CONTRIBUTING.md](CONTRIBUTING.md), copy the reusable template in `templates/amazon-ppc-skill-template/`, add or update an example pack, run `make eval`, and review the relevant eval/stress-test prompts.
 
 ## License
 

ROADMAP.md

@@ -11,7 +11,7 @@ Amazon PPC Advanced Skills should become an open-source library of expert agent
 - Turning findings into approval-ready action queues.
 - Teaching safe live-operation patterns for Rocketcart MCP and other execution layers.
 
-The skills must remain useful with static exports in Codex or Claude. Rocketcart MCP should be additive: live reads, preflight checks, snapshots, guarded execution, and readback.
+The skills must remain useful with static exports in Codex or Claude. Rocketcart MCP should be additive: live Amazon Ads reads, product intelligence, recent-change context, preflight checks, snapshots, guarded execution, and readback.
 
 ## Near-Term Priorities
 
@@ -29,7 +29,7 @@ The skills must remain useful with static exports in Codex or Claude. Rocketcart
 | `amazon-growth-opportunity-finder` | Production-oriented draft | Clearer thresholds for scale vs watchlist decisions by data volume. |
 | `amazon-account-growth-operating-system` | Orchestrator draft | More examples showing conflict resolution across upstream findings. |
 | `amazon-search-term-harvest-planner` | Good-first-skill complete | Fixture coverage for duplicate exact keywords and source-negative blockers. |
-| `rocketcart-amazon-ads-live-optimization-review` | Rocketcart bridge draft | Live-read examples, preflight examples, and post-change monitor skill. |
+| `rocketcart-amazon-ads-live-optimization-review` | Rocketcart bridge draft | Deeper product-intelligence examples, preflight examples, and post-change monitor skill. |
 
 ## Needed Before v1
 
@@ -107,20 +107,21 @@ Next good first skills:
 
 The first bridge skill is `rocketcart-amazon-ads-live-optimization-review`. Future Rocketcart-specific skills should follow the same read-first pattern:
 
-1. Read live state and historical analytics.
-2. Detect changes, risks, and opportunities.
-3. Propose exact action rows.
-4. Run preflight checks before any write.
-5. Require explicit approval for all material changes.
-6. Execute only the approved changes.
-7. Read back the resulting state and define monitoring windows.
+1. Read live Ads state and historical analytics.
+2. Join product intelligence: ASIN/SKU context, inventory, Featured Offer / Buy Box, category rank/BSR movement, price, reviews/rating, competitor signals, and product readiness where available.
+3. Detect changes, risks, and opportunities.
+4. Propose exact action rows.
+5. Run preflight checks before any write.
+6. Require explicit approval for all material changes.
+7. Execute only the approved changes.
+8. Read back the resulting state and define monitoring windows.
 
 Open-source skills should describe the workflow even when Rocketcart MCP is unavailable.
 
 ## Rocketcart Upper-Funnel Goals
 
 - Let operators prove value with static exports before they connect live tooling.
-- Make Rocketcart feel like the natural next layer for live reads, drift detection, preflight, readback, and monitoring.
+- Make Rocketcart feel like the natural next layer for live Ads reads, product intelligence, drift detection, preflight, readback, and monitoring.
 - Keep trust high by making no-write-by-default behavior obvious in README, examples, evals, and Rocketcart-specific skills.
 - Encourage agencies and AI builders to customize open-source skills while preserving Rocketcart-compatible action rows.
 - Turn repeated contributor ideas into Rocketcart-aware workflows only when live state materially improves safety or execution quality.

SECURITY.md

@@ -2,7 +2,7 @@
 
 ## Supported Scope
 
-This repository contains skill instructions, examples, docs, and lightweight validation checks. It does not contain a hosted service, credential manager, or Amazon Ads API client.
+This repository contains skill instructions, examples, docs, and lightweight validation checks. It does not contain a hosted service, credential manager, or live Amazon Ads client.
 
 ## Reporting Issues
 
@@ -11,7 +11,7 @@ Please open a GitHub issue for documentation, safety, or validation problems tha
 Do not publish:
 
 - Amazon Ads credentials or refresh tokens.
-- Rocketcart credentials, bearer tokens, MCP URLs, or customer workspace IDs.
+- Rocketcart credentials, private connection details, or customer workspace identifiers.
 - Real account IDs, profile IDs, campaign IDs, ASIN strategy maps, or proprietary account exports.
 - Customer names, email addresses, order data, or business-sensitive metrics.
 

amazon-ads-performance-drop-diagnosis/SKILL.md

@@ -35,7 +35,7 @@ Start every diagnosis with a data reliability and actionability gate:
 
 ## Workflow
 
-1. Establish data trust and exact windows.
+1. Establish data coverage, freshness, and exact windows.
    - Anchor recent windows on T-1 when current data may be incomplete.
    - Print exact date ranges used for L7, L14, L30, L60, L90, suspected drop, and baseline.
    - Separate SP, SB, and SD when the data supports it; do not blend ad types unless the user asks for an all-ad-type view.

amazon-search-term-harvest-planner/SKILL.md

@@ -67,7 +67,7 @@ Before recommending a source negative, check:
 
 ## Workflow
 
-1. Establish data trust.
+1. Establish data coverage and freshness.
    - State windows, ad types, report freshness, attribution caveats, search-term grain, missing source/destination fields, and duplicate-risk.
 
 2. Segment search terms.