# Ralph Progress Log

## Codebase Patterns

- RequestHunt CLI scripts in `skills/requesthunt/scripts/` are stdlib-only Python entrypoints that default to markdown-formatted summaries and must keep `--json` as a raw passthrough of the API response.
- RequestHunt scrape flows should send `depth` in the `/api/v1/scrape` payload and treat scrape cost as `depth x number of platforms`, while usage summaries now read from `usage.credits` instead of the removed realtime quota fields.
- RequestHunt scrape status responses expose job metadata on `data` and optional per-platform progress on `data.progress`; status views should render lifecycle fields directly from that object without reshaping the JSON payload.
- RequestHunt API key setup guidance should use the canonical `https://requesthunt.com/settings` URL; avoid the redirecting `/settings/api` path in CLI help text and docs.
- RequestHunt documentation should show `--depth` anywhere scrape commands are demonstrated and describe pricing in the unified credits model instead of the removed cached/realtime quota split.
- RequestHunt release bumps need the skill version synced across `skills/requesthunt/.claude-plugin/plugin.json`, the `skills.json` registry entry, and the `CHANGELOG.md` compatibility matrix plus `[Unreleased]` notes.

---

## 2026-03-31 11:03:20 CST - US-001
- Updated `skills/requesthunt/scripts/get_usage.py` to show the unified credits model instead of cached/realtime quotas.
- Added formatted output for `tier`, `credits`, optional `apiKeys`, and optional `rateLimit`, and corrected the API key help URL to `/settings`.
- Files changed: `skills/requesthunt/scripts/get_usage.py`, `.hal/prd.json`, `.hal/progress.txt`
- **Learnings for future iterations:**
  - Patterns discovered: RequestHunt scripts print human-readable markdown by default and preserve the untouched API payload behind `--json`.
  - Gotchas encountered: The RequestHunt API usage payload now hangs off `data.credits`, `data.apiKeys`, and `data.rateLimit`; older `cached` and `realtime` fields are obsolete.
  - Useful context: There is no nearby `AGENTS.md` under `skills/requesthunt`, so reusable module guidance should be captured in `.hal/progress.txt` unless a new local AGENTS file is introduced later.
---

## 2026-03-31 11:07:15 CST - US-002
- Added `--depth` support to `skills/requesthunt/scripts/scrape_topic.py`, including range validation, request payload wiring, and human-readable output for depth plus estimated credit cost.
- Switched the scrape script's usage summary from the obsolete realtime quota to unified credits, and corrected the missing API key help URL to `/settings`.
- Files changed: `skills/requesthunt/scripts/scrape_topic.py`, `.hal/prd.json`, `.hal/progress.txt`
- **Learnings for future iterations:**
  - Patterns discovered: Scrape scripts should preserve the raw API response for `--json` while deriving user-facing credit estimates from the request parameters.
  - Gotchas encountered: The scrape response may echo `data.depth`, but the usage summary now lives under `usage.credits`; `usage.realtime` should no longer be referenced.
  - Useful context: There is still no local `AGENTS.md` under `skills/requesthunt`, so reusable RequestHunt-specific guidance belongs in `.hal/progress.txt`.
---

## 2026-03-31 11:11:18 CST - US-003
- Added `skills/requesthunt/scripts/check_scrape.py` to fetch `GET /api/v1/scrape/{jobId}` and print a markdown status summary for RequestHunt scrape jobs.
- Implemented raw `--json` passthrough plus formatted output for job metadata, optional depth, per-platform progress, completed request counts, and failed-job errors.
- Files changed: `skills/requesthunt/scripts/check_scrape.py`, `.hal/prd.json`, `.hal/progress.txt`
- **Learnings for future iterations:**
  - Patterns discovered: Scrape status commands should read job lifecycle fields from `data` and render `data.progress` as platform-by-platform status lines when present.
  - Gotchas encountered: `completedAt`, `depth`, and `progress` are optional, so the formatted output needs to guard them while keeping the raw JSON untouched for `--json`.
  - Useful context: There is still no local `AGENTS.md` under `skills/requesthunt`, so RequestHunt-specific reusable guidance continues to live in `.hal/progress.txt`.
---

## 2026-03-31 11:15:12 CST - US-004
- Updated the missing-API-key help text in the remaining RequestHunt scripts to point at the canonical settings page.
- Verified the three CLIs still fail fast without an API key and now print `https://requesthunt.com/settings`.
- Files changed: `skills/requesthunt/scripts/list_requests.py`, `skills/requesthunt/scripts/search_requests.py`, `skills/requesthunt/scripts/get_topics.py`, `.hal/prd.json`, `.hal/progress.txt`
- **Learnings for future iterations:**
  - Patterns discovered: RequestHunt CLI entrypoints should all share the same canonical API-key help URL so users land on the non-redirecting settings page.
  - Gotchas encountered: This repo does not currently have a local `AGENTS.md` under `skills/requesthunt`, so reusable RequestHunt guidance still needs to be recorded in `.hal/progress.txt`.
  - Useful context: A quick smoke test with `REQUESTHUNT_API_KEY` unset is enough to validate the CLI help path without making any network calls.
---

## 2026-03-31 11:18:46 CST - US-005
- Updated `skills/requesthunt/SKILL.md` so the prerequisites and command examples reflect the v2 RequestHunt API.
- Added `--depth` to the scrape examples, documented the new `check_scrape.py` command, and replaced the obsolete cached/realtime limits with unified credit pricing and tier details.
- Files changed: `skills/requesthunt/SKILL.md`, `.hal/prd.json`, `.hal/progress.txt`
- **Learnings for future iterations:**
  - Patterns discovered: RequestHunt skill docs should describe scrape cost in terms of `depth x number of platforms` and show `--depth` anywhere scrape commands are demonstrated.
  - Gotchas encountered: The skill directory still has no nearby `AGENTS.md`, so RequestHunt-specific reusable guidance should keep accumulating in `.hal/progress.txt`.
  - Useful context: A focused content assertion script plus `git diff --check` is the practical validation path for documentation-only stories in this repo.
---

## 2026-03-31 11:22:48 CST - US-006
- Bumped the RequestHunt skill version to `2.0.0` in the Claude plugin manifest and the root skill registry, and updated the registry commands to advertise `check_scrape.py` plus `scrape_topic.py --depth`.
- Added the RequestHunt `2.0.0` unreleased changelog entry, updated the compatibility matrix, and replaced the obsolete cached/realtime quota note with unified credits pricing details.
- Files changed: `skills/requesthunt/.claude-plugin/plugin.json`, `skills.json`, `CHANGELOG.md`, `.hal/prd.json`, `.hal/progress.txt`
- **Learnings for future iterations:**
  - Patterns discovered: Skill release bumps in this repo should update both the per-skill plugin manifest and the root `skills.json` registry so marketplace metadata and installer listings stay aligned.
  - Gotchas encountered: `skills.json` contains many `version` fields, so target the named skill block carefully when bumping a single skill to avoid accidental edits elsewhere.
  - Useful context: For metadata-only stories, a JSON parse check, explicit content assertions, and `git diff --check` provide reliable coverage without needing network access.
---
