# Hermes Telegram Codex Coding Prompts — Amazon Price Watch Next Steps

Use these prompts one at a time in Hermes Telegram with the Codex model. Each prompt is self-contained and assumes the agent starts fresh.

Project root:

```text
/home/lin/.hermes/projects/amazon-price-watch
```

Global rules for every prompt:

- Load/read `AGENTS.md` first and follow it.
- Do not log in to Amazon.
- Do not bypass CAPTCHA or anti-bot protections.
- Do not commit `config/products.json`, `data/`, `backups/`, secrets, cookies, or unsanitized debug captures.
- Use TDD for behavior changes: failing test first, then implementation.
- Run verification before commit:
  - `uv run pytest -q`
  - `uv run ruff check .`
  - `uv run ruff format --check .`
  - `uv run ty check .`
  - `git diff --check`
- Commit only the logical unit requested by the prompt.

---

## Prompt 1 — Fix parser correctness bugs

```text
You are working in /home/lin/.hermes/projects/amazon-price-watch.

Task: fix two parser correctness issues found in engineering review.

First read:
- AGENTS.md
- docs/source-analysis/amazon-globalstore-cn.md
- src/amazon_price_watch/parser.py
- tests/test_parser.py

Scope:
1. Fix price fallback so Decimal("0.00") is treated as a valid price, not as missing. The current risk is using `discounted_price or original_price`; replace it with explicit `is None` logic.
2. Harden availability parsing so unrelated full-page text like a review containing “发货” does not automatically mark a product as `in_stock`. If no trusted availability region/pattern is found, prefer `Availability.UNKNOWN` over false `IN_STOCK`.

TDD requirements:
- Add a test proving `券后 ¥0.00` parses as price `Decimal("0.00")` with `SourceStatus.OK`.
- Add a test proving unrelated text such as `<div class="review">买家说发货慢</div>` does not mark availability as `in_stock`.
- Keep the existing real fixture test passing.

Implementation constraints:
- Do not add new runtime dependencies unless absolutely necessary; regex/local helpers are acceptable for this small fix.
- Do not broaden price extraction to page-wide yuan amounts.
- Do not change scraper/live behavior.

Verification:
- Run `uv run pytest tests/test_parser.py -q` after the targeted fix.
- Then run:
  - `uv run pytest -q`
  - `uv run ruff check .`
  - `uv run ruff format --check .`
  - `uv run ty check .`
  - `git diff --check`

Commit:
- Commit with message: `fix: harden parser price and availability handling`

Final response:
- Report files changed, tests run, commit hash, and any remaining parser limitations.
```

---

## Prompt 2 — Add parser fixture coverage for failure/page variants

```text
You are working in /home/lin/.hermes/projects/amazon-price-watch.

Task: add offline parser coverage for page variants before implementing storage/diff.

First read:
- AGENTS.md
- docs/source-analysis/amazon-globalstore-cn.md
- docs/methodology/2026-05-06-monitoring-automation-workflow-methodology.md
- src/amazon_price_watch/parser.py
- tests/test_parser.py

Scope:
Create small synthetic HTML fixtures or inline test samples for these parser states:
1. Blocked page -> `SourceStatus.BLOCKED`, price is null, explicit error.
2. Missing price but title exists -> `SourceStatus.PARSE_ERROR`, error `missing_price`.
3. Missing title but price exists -> `SourceStatus.PARSE_ERROR`, error includes `title`.
4. Out-of-stock/unavailable text -> `Availability.OUT_OF_STOCK` without price guessing.
5. Original-price fallback only inside scoped original-price area -> parses CNY price if discounted price is absent.

TDD requirements:
- Add tests first in `tests/test_parser.py`, or split into `tests/test_parser_variants.py` if cleaner.
- Prefer minimal synthetic HTML unless a real public fixture is already available and safe.
- Do not use `data/debug/` as a committed fixture source.

Implementation constraints:
- Only change parser if new tests reveal incorrect behavior.
- Do not add live network calls to tests.
- Do not commit local watchlists or debug captures.

Verification:
- Run `uv run pytest tests/test_parser.py -q` or the new targeted parser test file.
- Then run full gates:
  - `uv run pytest -q`
  - `uv run ruff check .`
  - `uv run ruff format --check .`
  - `uv run ty check .`
  - `git diff --check`

Commit:
- Commit with message: `test: cover parser page variants`

Final response:
- Report which variants are covered, tests run, commit hash, and any variants still needing real fixtures.
```

---

## Prompt 3 — Implement JSONL/latest storage layer

```text
You are working in /home/lin/.hermes/projects/amazon-price-watch.

Task: implement the storage layer for snapshots and latest state.

First read:
- AGENTS.md
- docs/plans/2026-05-06-amazon-price-watch-automation.md sections Phase 3 and data format
- src/amazon_price_watch/models.py
- tests/test_models.py

Scope:
Create:
- `src/amazon_price_watch/storage.py`
- `tests/test_storage.py`

Required behavior:
1. Append every `PriceSnapshot` to a JSONL file, default shape compatible with `PriceSnapshot.model_dump(mode="json")`.
2. Maintain latest state as a JSON object keyed by `product_id`.
3. Latest writes must be atomic: write temp file then replace.
4. Create parent directories as needed.
5. Preserve Decimal values as strings in JSON.
6. Provide functions that are easy for CLI/run to use later, for example:
   - `append_snapshot(path: Path, snapshot: PriceSnapshot) -> None`
   - `load_latest(path: Path) -> dict[str, PriceSnapshot]`
   - `save_latest(path: Path, snapshots: dict[str, PriceSnapshot]) -> None`
   - `update_latest(path: Path, snapshot: PriceSnapshot) -> None`

TDD requirements:
- Test append creates JSONL and appends multiple lines.
- Test load/save latest round-trips `PriceSnapshot` including Decimal price.
- Test update_latest replaces only the product key being updated.
- Test parent directories are created.

Implementation constraints:
- No database yet; JSONL/latest JSON only.
- No Hermes dependency.
- No absolute `/home/lin/...` paths in source.
- Do not write tests into real `data/`; use pytest `tmp_path`.

Verification:
- Run `uv run pytest tests/test_storage.py -q`.
- Then run full gates:
  - `uv run pytest -q`
  - `uv run ruff check .`
  - `uv run ruff format --check .`
  - `uv run ty check .`
  - `git diff --check`

Commit:
- Commit with message: `feat: add snapshot storage layer`

Final response:
- Report API functions created, tests run, commit hash, and any storage trade-offs.
```

---

## Prompt 4 — Implement diff and alert policy

```text
You are working in /home/lin/.hermes/projects/amazon-price-watch.

Task: implement pure diff/policy logic for price-drop and operational alert decisions.

First read:
- AGENTS.md
- docs/plans/2026-05-06-amazon-price-watch-automation.md Phase 4
- docs/methodology/2026-05-06-monitoring-automation-workflow-methodology.md Step 6
- src/amazon_price_watch/models.py
- src/amazon_price_watch/storage.py if present

Scope:
Create:
- `src/amazon_price_watch/diff.py`
- `tests/test_diff.py`

Required behavior:
Define a small typed decision model. Keep it simple; use dataclass or Pydantic consistently with the project.

Decision cases:
1. First successful observation: record only, no price alert.
2. Current OK price lower than previous successful OK price: alert type `price_drop`.
3. Current OK price equal/higher than previous successful OK price: record only, no alert.
4. Previous failed/non-ok and current OK: recovery record; alert only if current price is lower than last successful price when available.
5. Current non-ok status (`captcha`, `blocked`, `parse_error`, `network_error`): operational alert.
6. `alert_below` threshold in `ProductConfig`: alert when current OK price is below threshold, but avoid duplicate noisy alerts if already below and unchanged unless the design explicitly records it as repeat-suppressed.

TDD requirements:
- Tests must use constructed `PriceSnapshot` objects; no network and no file I/O.
- Include exact tests for price drop, price increase, no previous, non-ok current, and threshold.
- Use Decimal comparisons, not float.

Implementation constraints:
- Do not format Telegram text here; this module returns structured decisions only.
- Do not read/write storage here.
- Do not treat price increases as price alerts.

Verification:
- Run `uv run pytest tests/test_diff.py -q`.
- Then full gates:
  - `uv run pytest -q`
  - `uv run ruff check .`
  - `uv run ruff format --check .`
  - `uv run ty check .`
  - `git diff --check`

Commit:
- Commit with message: `feat: add price watch diff policy`

Final response:
- Report decision cases implemented, tests run, commit hash, and any intentionally deferred policy such as cooldown persistence.
```

---

## Prompt 5 — Implement notification formatter

```text
You are working in /home/lin/.hermes/projects/amazon-price-watch.

Task: implement deterministic notification text formatting. Hermes cron/Telegram delivery will consume stdout later; core code must not call Telegram APIs directly.

First read:
- AGENTS.md
- docs/plans/2026-05-06-amazon-price-watch-automation.md Phase 5
- src/amazon_price_watch/diff.py
- src/amazon_price_watch/models.py

Scope:
Create:
- `src/amazon_price_watch/notify.py`
- `tests/test_notify.py`

Required behavior:
1. Format price-drop alerts in concise Chinese Telegram-ready text.
2. Include product title/name if available, current price, previous price, delta, availability, and URL.
3. Format operational alerts separately for non-ok statuses with status and error.
4. Return empty string or no messages when decisions do not require notification.
5. Support combining multiple alert messages deterministically with a stable separator.

Example price-drop text:

Amazon 价格变动：Example Product
- 当前：CNY 579.00
- 上次：CNY 629.00
- 变化：降价 CNY 50.00
- 状态：in_stock
- 链接：https://globalstore.amazon.cn/dp/B000000000

TDD requirements:
- Test price drop formatting exactly.
- Test no-change returns no message.
- Test operational alert formatting.
- Test multiple alerts are deterministic.

Implementation constraints:
- No Telegram API calls.
- No Hermes imports.
- No file I/O.
- Keep output suitable for Telegram markdown but avoid complex tables.

Verification:
- Run `uv run pytest tests/test_notify.py -q`.
- Then full gates:
  - `uv run pytest -q`
  - `uv run ruff check .`
  - `uv run ruff format --check .`
  - `uv run ty check .`
  - `git diff --check`

Commit:
- Commit with message: `feat: add notification formatter`

Final response:
- Report formatter functions, examples tested, commit hash, and stdout contract.
```

---

## Prompt 6 — Implement end-to-end `run` command

```text
You are working in /home/lin/.hermes/projects/amazon-price-watch.

Task: replace the placeholder `run` command with an end-to-end local worker loop.

First read:
- AGENTS.md
- README.md
- docs/plans/2026-05-06-amazon-price-watch-automation.md Phase 5 Task 5.2
- src/amazon_price_watch/cli.py
- src/amazon_price_watch/config.py
- src/amazon_price_watch/scraper.py
- src/amazon_price_watch/storage.py
- src/amazon_price_watch/diff.py
- src/amazon_price_watch/notify.py

Scope:
Modify:
- `src/amazon_price_watch/cli.py`
Create or modify tests:
- `tests/test_run_command.py`

Required behavior:
1. `run --config PATH` loads products.
2. For each product, calls the scraper adapter and gets a `PriceSnapshot`.
3. Appends every snapshot to `data/snapshots.jsonl` by default.
4. Updates `data/latest.json` by default.
5. Computes decisions using previous latest state before update.
6. Prints notification text only if alerts exist. Empty stdout means no Telegram message.
7. Writes JSON run report under `data/runs/YYYYMMDDTHHMMSSZ.json` by default.
8. `--dry-run` must not write state files but may print what would notify.
9. Add CLI options if needed, for example `--data-dir`, but keep defaults relative to project root.
10. Exit code should be 0 if the run completed, even if some products had operational alert decisions; config errors remain 2.

TDD requirements:
- Mock `scrape_product` in CLI tests; do not perform network calls.
- Use `tmp_path` for data dir.
- Test dry-run writes no files.
- Test no alert prints empty stdout.
- Test price drop prints notification text and writes report/state when not dry-run.
- Test non-ok snapshot produces operational notification.

Implementation constraints:
- Do not call Telegram APIs.
- Do not hardcode `/home/lin/...` in source.
- Do not commit generated `data/` files.
- Keep run orchestration thin; storage/diff/notify logic should stay in their modules.

Verification:
- Run `uv run pytest tests/test_run_command.py -q`.
- Run smoke:
  - `uv run amazon-price-watch run --config config/products.example.json --dry-run`
- Then full gates:
  - `uv run pytest -q`
  - `uv run ruff check .`
  - `uv run ruff format --check .`
  - `uv run ty check .`
  - `git diff --check`

Commit:
- Commit with message: `feat: implement watch run command`

Final response:
- Report CLI behavior, tests run, smoke output, commit hash, and whether real `config/products.json` was touched.
```

---

## Prompt 7 — Implement `health` command and stale-data guard

```text
You are working in /home/lin/.hermes/projects/amazon-price-watch.

Task: implement health checks so failures are visible even when no price changes happen.

First read:
- AGENTS.md
- docs/plans/2026-05-06-amazon-price-watch-automation.md Phase 6
- src/amazon_price_watch/cli.py
- src/amazon_price_watch/storage.py
- src/amazon_price_watch/models.py

Scope:
Create:
- `src/amazon_price_watch/health.py`
- `tests/test_health.py`
Modify:
- `src/amazon_price_watch/cli.py`

Required behavior:
1. `health --max-age-hours 30` checks latest successful observations.
2. Healthy state: exit 0 and print nothing.
3. Stale latest successful snapshot older than threshold: exit non-zero and print concise actionable text.
4. Product configured but missing from latest state: unhealthy.
5. Last run report all products failed: unhealthy.
6. Missing state files: unhealthy unless an explicit option like `--allow-empty` is added for bootstrap; default should not silently pass once scheduled.
7. Add `--config` and `--data-dir` options if needed.

TDD requirements:
- Use `tmp_path` for latest and run reports.
- Test healthy quiet behavior.
- Test stale latest snapshot.
- Test missing product.
- Test all-failed last run report.
- Test CLI exit codes and stdout/stderr behavior.

Implementation constraints:
- No network calls.
- No Telegram API calls.
- No hardcoded absolute paths.
- Keep messages short because Hermes cron may deliver stdout/stderr.

Verification:
- Run `uv run pytest tests/test_health.py -q`.
- Run smoke if local state exists:
  - `uv run amazon-price-watch health --config config/products.json --max-age-hours 30`
  If local state does not exist yet, explain expected unhealthy/bootstrap behavior.
- Then full gates:
  - `uv run pytest -q`
  - `uv run ruff check .`
  - `uv run ruff format --check .`
  - `uv run ty check .`
  - `git diff --check`

Commit:
- Commit with message: `feat: add health checks`

Final response:
- Report health rules implemented, tests run, commit hash, and any bootstrap caveat.
```

---

## Prompt 8 — Update docs and README to match implemented status

```text
You are working in /home/lin/.hermes/projects/amazon-price-watch.

Task: update project documentation so it accurately reflects what is implemented and how to operate it manually.

First read:
- AGENTS.md
- README.md
- docs/plans/2026-05-06-amazon-price-watch-automation.md
- docs/source-analysis/amazon-globalstore-cn.md
- docs/methodology/2026-05-06-monitoring-automation-workflow-methodology.md

Scope:
Modify docs only unless you find a broken command in docs that requires a tiny code fix; if code changes are needed, stop and report before making them.

Required documentation updates:
1. README: add `Current status` with implemented vs not implemented, or update it if run/health are now implemented.
2. README: add manual commands for validate-config, scrape-one, run dry-run, run real, and health.
3. README: state stdout contract: empty stdout means no Telegram notification; non-empty stdout is message-worthy.
4. Source analysis: update verification section to match actual run/health behavior.
5. Methodology: add lessons learned from engineering review if not already present:
   - explicit `is None` for numeric fallback
   - scoped availability/status parsing
   - do not schedule placeholders

Verification:
- Run `git diff --check`.
- Run the documented commands that are safe and local:
  - `uv run amazon-price-watch --help`
  - `uv run amazon-price-watch validate-config --config config/products.example.json`
  - `uv run amazon-price-watch run --config config/products.example.json --dry-run`
  - health smoke if implemented and safe
- Then run full gates if any code changed; for docs-only, still run `uv run pytest -q` if time permits.

Commit:
- Commit with message: `docs: update monitoring workflow status`

Final response:
- Report docs changed, commands verified, commit hash, and any docs intentionally left as future-plan sections.
```

---

## Prompt 9 — Manual real-run verification against local watchlist

```text
You are working in /home/lin/.hermes/projects/amazon-price-watch.

Task: perform a manual real-run verification against the local watchlist before scheduling. This is verification only; do not change code unless a clear bug is found, and do not commit local state.

First read:
- AGENTS.md
- README.md
- config/products.example.json
- Check whether `config/products.json` exists but do not print sensitive/local-only content in full.

Preconditions:
- `run`, `storage`, `diff`, `notify`, and `health` should already be implemented.
- If not implemented, stop and report which prompt/task must be completed first.

Steps:
1. Check git status.
2. Validate configs:
   - `uv run amazon-price-watch validate-config --config config/products.example.json`
   - If `config/products.json` exists: `uv run amazon-price-watch validate-config --config config/products.json`
3. Run dry-run:
   - `uv run amazon-price-watch run --config config/products.json --dry-run`
4. Run real once:
   - `uv run amazon-price-watch run --config config/products.json`
5. Run health:
   - `uv run amazon-price-watch health --config config/products.json --max-age-hours 30`
6. Run full gates:
   - `uv run pytest -q`
   - `uv run ruff check .`
   - `uv run ruff format --check .`
   - `uv run ty check .`
   - `git diff --check`

Rules:
- Do not commit `data/` or `config/products.json`.
- If the real run writes local state under `data/`, that is expected but ignored.
- If Amazon returns CAPTCHA/block/network error, do not bypass; report exact `source_status` and debug evidence path if created.
- If stdout is non-empty, include it in the final report because it is what Telegram would receive.

Commit:
- Do not commit unless you made tracked doc/code fixes. If you did, commit only tracked fixes after verification.

Final response:
- Report dry-run output, real-run output, health output/exit behavior, tests run, git status, and whether the project is ready for scheduling.
```

---

## Prompt 10 — Create Hermes cron wrapper and schedule only after manual gate passes

```text
You are working on the Hermes machine and project /home/lin/.hermes/projects/amazon-price-watch.

Task: create a Hermes cron no-agent wrapper for daily Amazon price watch notifications, but only if the manual real-run gate has passed.

First read:
- AGENTS.md
- README.md
- docs/plans/2026-05-06-amazon-price-watch-automation.md Phase 7

Precondition gate:
Before creating any cron job, verify and report:
1. `uv run amazon-price-watch run --config config/products.json --dry-run` succeeds.
2. `uv run amazon-price-watch run --config config/products.json` succeeds or returns only explicit handled operational statuses.
3. `uv run amazon-price-watch health --config config/products.json --max-age-hours 30` behaves as expected.
4. `git status --short` has no unexpected tracked changes.

If any gate fails, stop. Do not schedule cron.

Wrapper requirements:
- Create script under `~/.hermes/scripts/amazon_price_watch.sh`.
- The script must:
  - `cd /home/lin/.hermes/projects/amazon-price-watch`
  - run `uv run amazon-price-watch run --config config/products.json`
  - then run `uv run amazon-price-watch health --config config/products.json --max-age-hours 30`
- stdout contract:
  - empty stdout means no Telegram message
  - non-empty stdout is delivered as notification
  - non-zero exit should alert as cron failure
- Do not put secrets in the script.
- Make the script executable.

Cron requirements:
- Use Hermes cron no-agent mode.
- Delivery target should be this Telegram/origin chat unless user has specified another target.
- Schedule daily. If no exact time has been confirmed, choose a conservative morning default and state it clearly.
- Do not recursively schedule additional cron jobs.

Verification:
- Run the wrapper manually once.
- List cron jobs after creation and report the job id.
- Do not commit `~/.hermes/scripts` into the project repo.
- If you update project docs/runbook, commit that doc-only change separately after tests or at least `git diff --check`.

Final response:
- Report wrapper path, manual wrapper output, cron job id, schedule, delivery target, and rollback command/job removal instruction.
```

---

## Prompt 11 — Final engineering review before declaring MVP complete

```text
You are working in /home/lin/.hermes/projects/amazon-price-watch.

Task: perform a final engineering review before declaring the MVP complete. Read-only unless you find small doc corrections; do not make feature changes in this prompt.

First read:
- AGENTS.md
- README.md
- docs/plans/2026-05-06-amazon-price-watch-automation.md
- docs/source-analysis/amazon-globalstore-cn.md
- docs/methodology/2026-05-06-monitoring-automation-workflow-methodology.md
- src/amazon_price_watch/*.py
- tests/*.py

Review dimensions:
1. MVP boundary: public-only, no login, no CAPTCHA bypass, no auto-buy, no personal data.
2. Implementation loop: config -> scrape -> parse -> storage -> diff -> notify stdout -> health.
3. Data integrity: Decimal prices, explicit statuses, no false price guessing, latest/snapshot consistency.
4. Operational behavior: empty stdout/no notification, non-empty stdout/message, health catches stale state.
5. Test coverage: parser variants, storage, diff, notify, run, health, CLI.
6. Portability: no hardcoded `/home/lin/...` in source, Hermes only in runtime docs/wrapper.
7. Git hygiene: no local watchlist, data, backups, or debug captures tracked.

Commands:
- `git status --short`
- `git ls-files`
- `uv run pytest -q`
- `uv run ruff check .`
- `uv run ruff format --check .`
- `uv run ty check .`
- `git diff --check`
- `uv run amazon-price-watch validate-config --config config/products.example.json`
- If local config exists: `uv run amazon-price-watch validate-config --config config/products.json`
- Run safe smoke commands for `run --dry-run` and `health`.

Output required:
- Verdict: pass / pass with quality debt / fail.
- What exactly is implemented.
- Remaining blockers before MVP complete.
- Risks by severity.
- Exact verification evidence.
- Git status.

Commit:
- Do not commit unless you only fixed docs typos; if committed, report hash.
```