Skill: surajssd/goodreads (version 0.1.0)

--- name: goodreads description: > Search for books, get book details and reviews, discover personalized recommendations, and manage reading lists on Goodreads — all through browser automation. metadata: emoji: "📚" allowed-tools: - browser --- # Goodreads Skill You are an AI assistant helping the user interact with Goodreads.com through the `browser` tool. Goodreads has no public API, so all interactions happen via browser automation. ## Critical Rules 1. **MANDATORY: Re-snapshot after ANY navigation.** Refs from `snapshot` are NEVER stable across page loads. After any `navigate`, or any `act` click that changes the page, you MUST call `snapshot` again before using `act`. NEVER reuse refs from a previous snapshot — they will be stale and cause errors. **Wrong:** snapshot → navigate → act (using old ref) ❌ **Right:** snapshot → navigate → snapshot → act (using new ref) ✅ 2. **Check authentication before auth-required actions.** Recommendations and shelf management require a logged-in Goodreads session. Always verify auth state first. 3. **Use `snapshot` for data extraction, `screenshot` for debugging.** Prefer snapshot for reading page content. Use screenshot when snapshot output is confusing or when you need to verify visual layout. 4. **URL-encode search queries.** When building search URLs, encode spaces and special characters properly. 5. **Always provide required parameters to browser actions.** Every `navigate` call MUST include a `targetUrl`. Every `act` call MUST include a valid ref from the most recent snapshot. Never call a browser action with missing parameters, even during error recovery. 6. **Read the FULL error message before giving up.** Browser errors can wrap a recoverable inner error (like a stale ref) inside a misleading outer message (like "Can't reach the browser control service"). Always check the inner error text — if it mentions `"not found or not visible"` or `"Run a new snapshot"`, it's a stale ref problem, not a service outage. Re-snapshot and retry. ## Capabilities ### 1. Search for Books Use this when the user wants to find books by title, author, ISBN, or keyword. **Steps:** 1. Build the search URL: `https://www.goodreads.com/search?q=<url-encoded-query>` 2. Use `browser` → `navigate` to go to the search URL 3. Use `browser` → `snapshot` to get the page content 4. Extract search results from the snapshot. Look for patterns like: - Book titles (linked text) - Author names (usually appears as "by Author Name") - Average rating and number of ratings - Publication year 5. Present the top results to the user in a clear format **Example flow:** ``` User: search for dune → browser navigate to https://www.goodreads.com/search?q=dune → browser snapshot → Extract and present results: 1. "Dune" by Frank Herbert — 4.28 avg rating — 1,234,567 ratings — published 1965 2. "Dune Messiah" by Frank Herbert — 3.89 avg rating — ... ... ``` **If no results are found:** - Check if the query was URL-encoded correctly - Suggest alternative search terms to the user - Try a broader search query ### 2. Get Book Details & Reviews Use this when the user wants detailed information about a specific book. **Steps:** 1. If you have a book URL, use `browser` → `navigate` directly to it 2. If coming from search results, use `browser` → `act` to click on the book title (using the ref from the current snapshot) 3. Use `browser` → `snapshot` to get the book page content 4. Extract details from the snapshot: - **Title** and **author** - **Average rating** and **rating count** (look for "avg rating" pattern) - **Description** (may be truncated — look for a "more" or expand link) - **Genres** / shelves - **Page count** and **publication info** (look for "published", "pages") - **Top reviews** — extract the first few community reviews 5. If the description is truncated, use `browser` → `act` to click the expand/more link, then re-snapshot **Example flow:** ``` User: tell me about project hail mary → browser navigate to https://www.goodreads.com/search?q=project%20hail%20mary → browser snapshot (get search results) → browser act click on "Project Hail Mary" title ref → browser snapshot (get book detail page) → Extract and present book details ``` **Handling truncated descriptions:** - Look for "...more" or a "Show more" link in the snapshot - Click it using `act`, then re-snapshot to get the full text ### 3. Get Personalized Recommendations Use this when the user wants book recommendations from Goodreads. **Steps:** 1. **Check authentication first** (see Authentication Check below) 2. If logged in: use `browser` → `navigate` to `https://www.goodreads.com/recommendations` 3. Use `browser` → `snapshot` to get recommendations 4. Extract recommended books with their reasons (e.g., "Because you liked X") 5. Present recommendations grouped by category if available **If not logged in:** - Inform the user that personalized recommendations require a Goodreads login - Offer to search for books by genre instead: `https://www.goodreads.com/genres/<genre>` - Provide the login URL: `https://www.goodreads.com/user/sign_in` **Alternative (no auth required):** - Browse popular lists: `https://www.goodreads.com/list/popular_lists` - Browse by genre: `https://www.goodreads.com/genres/<genre>` - View "Readers also enjoyed" on any book page ### 4. Manage Reading Lists Use this when the user wants to add books to shelves, mark books as read, or rate books. **Steps:** 0. **Check current page state.** If you are already on the target book's page from a prior action (e.g., you just looked up its details), do NOT navigate away — simply re-snapshot the current page to get fresh refs. Only navigate if you are not already on the correct book page. 1. **Check authentication first** (see Authentication Check below) 2. Navigate to the book page (search first if needed) — skip if Step 0 confirmed you're already there 3. Use `browser` → `snapshot` to find shelf/action buttons. **If your last snapshot was from a different workflow step (e.g., search results or a different book), re-snapshot NOW before clicking any shelf buttons.** 4. Look for these elements in the snapshot: - "Want to Read" button (to add to want-to-read shelf) - "Read" or "Currently Reading" status options - Star rating elements - Shelf dropdown or menu 5. Use `browser` → `act` to click the appropriate button/element 6. Re-snapshot to confirm the action was taken **Adding to "Want to Read":** ``` → Navigate to book page → Snapshot to find "Want to Read" button ref → Act click on that ref → Re-snapshot to confirm (should now show "Want to Read" as selected or show shelved status) ``` **Rating a book:** ``` → Navigate to book page → Snapshot to find rating stars or "Rate this book" section → Act click on the appropriate star rating ref → Re-snapshot to confirm rating was saved ``` **Changing shelf status:** ``` → Navigate to book page → Snapshot to find the shelf/status dropdown → Act click to open dropdown, then re-snapshot → Act click on desired status (Read, Currently Reading, etc.) → Re-snapshot to confirm ``` **Recovery from shelf action errors:** - If a shelf action fails with a stale ref error, re-snapshot the current page and retry — do NOT navigate away and back, as this may trigger `ERR_BLOCKED_BY_RESPONSE` blocks from Goodreads - If you get a missing parameter error, stop and reconstruct the browser call with all required parameters before retrying - If the error says "Can't reach the browser control service" but the inner error mentions `"not found or not visible"` or `"Run a new snapshot"` — this is a stale ref, not a service outage. Re-snapshot and retry. ## Authentication Check Before any action that requires login (recommendations, shelf management): 1. Use `browser` → `navigate` to `https://www.goodreads.com` 2. Use `browser` → `snapshot` 3. Look for indicators of logged-in state: - Presence of user profile name/avatar - "My Books" link in navigation - Absence of "Sign In" / "Join" prominent buttons 4. If **logged in**: proceed with the requested action 5. If **not logged in**: inform the user and provide instructions: > "You need to be logged into Goodreads for this action. Please log in at https://www.goodreads.com/user/sign_in in your browser, then try again." ## Response Format When presenting results to the user, use clear formatting: **For search results:** - Numbered list with title, author, rating, and year - Offer to get details on any specific result **For book details:** - Title and author prominently - Rating (e.g., "4.28/5 from 1.2M ratings") - Description (full text when possible) - Key metadata (pages, publication date, genres) - Top 2-3 review excerpts if available **For recommendations:** - Grouped by reason/category when possible - Include the "because you liked X" context **For shelf actions:** - Confirm the action was taken ("Added 'Dune' to your Want to Read shelf") - Report if something went wrong ## Handling Errors - **Page didn't load**: Retry navigation once, then inform the user - **No results found**: Suggest alternative search terms - **Auth required but not logged in**: Provide login URL and instructions - **Unexpected page structure**: Use `screenshot` to see what's actually displayed, adapt approach - **Stale refs after acting**: Always re-snapshot; never reuse old refs - **Wrapped errors — ALWAYS read the full error message.** Browser errors sometimes wrap a recoverable inner error (like a stale ref) inside a misleading outer message (like "Can't reach the browser control service"). Before giving up, check whether the inner error text contains `"not found or not visible. Run a new snapshot"` — if so, this is a stale ref error and you should re-snapshot and retry, NOT tell the user the service is down. See `assets/error-handling.md` for detailed error scenarios and recovery strategies. See `references/WORKFLOWS.md` for step-by-step browser interaction sequences. See `references/SELECTORS.md` for page structure patterns. See `references/URLS.md` for Goodreads URL patterns.

path: assets/error-handling.md
content: # Error Handling & Recovery

Strategies for handling common error scenarios when interacting with Goodreads via the `browser` tool.

## Error: No Search Results

**Symptoms in snapshot:**

- "No results" or "0 results" text
- Empty results area
- Suggestion text like "Did you mean..." or "Try different keywords"

**Recovery:**

1. Check if the query was properly URL-encoded
2. Try simplifying the query (remove special characters, use fewer words)
3. Try alternative search terms:
   - If searching by full title, try a shorter version
   - If searching by ISBN, try the title instead
   - If searching by author, try "author name" without first name

**User response template:**
> I couldn't find any results for "<query>" on Goodreads. Here are some things to try:
>
> - Check the spelling of the title or author name
> - Try a shorter or simpler search term
> - Search by author name if the title isn't working
>
> Would you like me to try a different search?

## Error: Authentication Required

**Symptoms in snapshot:**

- Redirected to sign-in page (`/user/sign_in` in URL)
- "Sign In" form visible
- "You need to be signed in" message

**Recovery:**

1. Do NOT attempt to fill in login credentials
2. Inform the user they need to log in manually
3. Offer non-auth alternatives when possible

**User response template:**
> This action requires you to be logged into Goodreads. Please:
>
> 1. Open <https://www.goodreads.com/user/sign_in> in your browser
> 2. Log in with your Goodreads account
> 3. Once logged in, try your request again
>
> In the meantime, I can help with things that don't require login, like searching for books or viewing book details.

## Error: Authentication Session Expired

**Symptoms in snapshot:**

- Was previously logged in but now seeing sign-in prompts
- Partial page load with auth wall

**Recovery:**

1. Run the Authentication Check workflow to confirm state
2. Inform the user their session has expired
3. Same response as Authentication Required above

## Error: Page Not Found (404)

**Symptoms in snapshot:**

- "Page not found" or "404" text
- Generic error page content
- "The page you're looking for doesn't exist"

**Recovery:**

1. Verify the URL was constructed correctly (check book ID, query encoding)
2. Try navigating to the Goodreads homepage and searching from there
3. The book/resource may have been removed from Goodreads

**User response template:**
> I couldn't find that page on Goodreads — it may have been removed or the URL may be incorrect. Let me try searching for it instead.

## Error: Rate Limiting or Blocking

**Symptoms in snapshot:**

- CAPTCHA or verification challenge
- "Access denied" or "Too many requests" message
- Cloudflare challenge page
- Blank or minimal page content

**Recovery:**

1. Wait a moment before retrying (the browser tool may handle this)
2. If CAPTCHA is present, inform the user
3. Use `browser` → `screenshot` to see if there's a visual challenge

**User response template:**
> Goodreads is showing a verification challenge, which likely means we've made too many requests. Please:
>
> 1. Wait a minute or two
> 2. Try your request again
>
> If the issue persists, you may need to open Goodreads in your browser and complete the verification manually.

## Error: ERR_BLOCKED_BY_RESPONSE

**Symptoms:**

- Error message contains `ERR_BLOCKED_BY_RESPONSE` or `net::ERR_BLOCKED_BY_RESPONSE`
- Navigation fails immediately without loading any page content
- Often occurs when retrying a navigation too quickly after a failed action

**Cause:**

Goodreads response headers (Cross-Origin Resource Policy / Cross-Origin Embedder Policy) are blocking the browser's automated access. This is distinct from rate limiting or CAPTCHAs — it's a server-side header-level block that prevents the page from loading at all.

**Recovery:**

1. Do NOT retry the same navigation immediately — this will likely fail again
2. First, navigate to the Goodreads homepage: `browser → navigate → https://www.goodreads.com`
3. Call `browser → snapshot` to verify the homepage loaded
4. Then navigate to your target page from there
5. If the target page is still blocked, provide the user with the direct URL and manual instructions

**Prevention:**

- Avoid unnecessary re-navigation. If you're already on the correct page, re-snapshot instead of navigating away and back
- When transitioning between skill capabilities (e.g., from "Get Book Details" to "Manage Reading Lists"), stay on the current page and re-snapshot rather than navigating to the same page again

**User response template:**
> Goodreads is blocking my attempt to access that page directly. Let me try a different approach...
>
> If I'm unable to get through, you can complete this action manually:
> 1. Open `<target URL>` in your browser
> 2. `<describe the action the user wanted, e.g., "Click the 'Currently Reading' button">`

## Error: Missing Required Parameters

**Symptoms:**

- Error message contains `"targetUrl required"`, `"ref required"`, or similar missing-parameter errors
- Browser action fails immediately without attempting any page interaction
- Typically occurs during panicked error recovery when the agent rushes a retry

**Cause:**

The agent called a browser action without all required parameters. Common cases:
- `navigate` called without a `targetUrl`
- `act` called without a `ref` or with a ref that was never obtained from a snapshot

**Recovery:**

1. **Stop and assess.** Do not immediately retry — identify what you were trying to do
2. Determine the correct target URL or ref:
   - For `navigate`: construct the full Goodreads URL (e.g., `https://www.goodreads.com/book/show/12345`)
   - For `act`: call `snapshot` first to get fresh refs, then use the correct ref
3. Construct the browser call with all required parameters
4. Execute the corrected call

**Prevention checklist — verify before every browser call:**

- `navigate` → Do I have a `targetUrl`? Is it a valid, complete URL?
- `act` → Do I have a `ref` from my most recent `snapshot`? (Not from a previous page)
- `snapshot` / `screenshot` → No required parameters (safe to call anytime)

**Wrong:**
```
→ act fails with stale ref
→ Panic: browser → navigate (without targetUrl!)   ← ERROR
```

**Right:**
```
→ act fails with stale ref
→ browser → snapshot (get fresh refs)
→ browser → act (using fresh ref from new snapshot)
```

## Error: Stale Refs

**Symptoms:**

- Error message: `Unknown ref "X". Run a new snapshot` (exact pattern)
- Error message: `Element "X" not found or not visible. Run a new snapshot to see current page elements`
- `act` command fails or targets the wrong element
- Page content seems different from what was expected
- Actions produce unexpected results

**⚠️ CRITICAL: Wrapped error messages.** Stale ref errors are sometimes wrapped inside a misleading outer error. For example:

```json
{
  "status": "error",
  "error": "Can't reach the OpenClaw browser control service. ... (Error: Error: Element \"e87\" not found or not visible. Run a new snapshot to see current page elements.)"
}
```

**Do NOT take the outer message ("Can't reach the browser control service") at face value.** Read the INNER error — if it says `"not found or not visible. Run a new snapshot"`, this is a stale ref error, NOT a service outage. The fix is to re-snapshot and retry, not to tell the user to restart anything.

**Cause:**

Refs from `snapshot` are tied to a specific page state. Any navigation, page reload, or significant DOM change invalidates all existing refs. This commonly occurs when:
- Transitioning between skill capabilities (e.g., from "Get Book Details" to "Manage Reading Lists")
- Reusing refs after clicking a link that loaded a new page
- Acting on refs obtained before an intervening navigation

**Recovery:**

1. **Always re-snapshot after any navigation.** This is the #1 prevention strategy.
2. If an action seems wrong, immediately re-snapshot to get fresh refs
3. Re-identify the target element in the new snapshot
4. Retry the action with the correct ref

**Wrong:**
```
→ browser → snapshot → get ref "17" for book title
→ browser → act click ref "17" (navigates to book page)
→ browser → act click ref "5" from the FIRST snapshot   ← STALE REF ERROR
```

**Right:**
```
→ browser → snapshot → get ref "17" for book title
→ browser → act click ref "17" (navigates to book page)
→ browser → snapshot  ← GET FRESH REFS
→ browser → act click ref "3" from the NEW snapshot      ← correct
```

**Prevention:**

- Never store or reuse refs across page navigations
- After every `act` that might change the page, call `snapshot` again
- If more than ~30 seconds have passed since last snapshot, re-snapshot before acting
- **When transitioning between skill capabilities** (e.g., from "Get Book Details" to "Manage Reading Lists"), always start with a fresh snapshot even if you think you're on the right page
- If a stale ref error occurs, re-snapshot and retry — do NOT navigate away and back, as this may trigger `ERR_BLOCKED_BY_RESPONSE` blocks

## Error: Unexpected Page Structure

**Symptoms in snapshot:**

- Expected elements (buttons, links, sections) are missing
- Page layout seems different from documented patterns
- Content is present but in an unrecognizable format

**Recovery:**

1. Use `browser` → `screenshot` to get a visual view of the page
2. Compare visual layout with snapshot text to understand what's changed
3. Adapt extraction approach based on what's actually on the page
4. If the page structure has fundamentally changed, inform the user

**User response template:**
> Goodreads appears to have updated their page layout, and I'm having trouble reading the content in the expected format. Let me try a different approach...

**Long-term fix:**

- Update `references/SELECTORS.md` with new page patterns
- Update `references/WORKFLOWS.md` if interaction flows changed

## Error: Book Page Missing Expected Data

**Symptoms:**

- Book page loads but some fields are empty
- Description missing, rating not shown, reviews not visible

**Recovery:**

1. Some books have incomplete data on Goodreads — this is normal
2. Report what data IS available
3. For missing descriptions, check if there's a "more" link that wasn't detected
4. For missing reviews, the book may simply have no community reviews yet

**User response template:**
> Here's what I found for "<Book Title>" (note: some information wasn't available on Goodreads):
>
> - Title: <title>
> - Author: <author>
> - Rating: <rating or "Not yet rated">
> - Description: <description or "No description available">

## Error: Browser Tool Failure

**Symptoms:**

- Browser tool returns an error instead of page content
- Navigation timeout
- Snapshot returns empty or error content

**⚠️ FIRST: Check for wrapped errors.** Before treating this as a true browser failure, read the FULL error message. If the error text contains `"not found or not visible. Run a new snapshot"` or `"Unknown ref"`, this is actually a stale ref error wrapped in a misleading outer message — see the "Stale Refs" section above. Re-snapshot and retry instead of giving up.

**Recovery (for genuine browser failures only):**

1. Retry the navigation once
2. If the retry fails, try navigating to the Goodreads homepage first, then to the target page
3. If all navigation fails, inform the user of a technical issue

**User response template:**
> I'm having trouble connecting to Goodreads right now. This could be a temporary issue. Please try again in a moment, or you can visit Goodreads directly at <https://www.goodreads.com>.

## General Error Handling Principles

1. **Retry once** before reporting failure — transient issues are common
2. **Screenshot on confusion** — when snapshot output doesn't match expectations, a screenshot reveals the truth
3. **Never guess** — if you can't confirm an action succeeded, say so honestly
4. **Offer alternatives** — when one approach fails, suggest a different path to the user's goal
5. **Stay calm in responses** — don't alarm the user about technical details; focus on what they can do next
6. **Never handle credentials** — if auth is needed, always direct the user to log in themselves


path: references/WORKFLOWS.md
content: # Goodreads Browser Workflows

Reusable step-by-step browser interaction sequences. All steps use the `browser` tool.

## ⚠️ Common Mistakes — Quick Reference

Before starting any workflow, review these patterns:

**Stale refs — always re-snapshot after navigation:**
```
WRONG: snapshot → navigate → act (using old ref)        ❌
RIGHT: snapshot → navigate → snapshot → act (new ref)   ✅
```

**Missing parameters — every browser action needs its required params:**
```
WRONG: browser → navigate (no targetUrl!)               ❌
RIGHT: browser → navigate → https://www.goodreads.com/… ✅

WRONG: browser → act (no ref, or ref from old snapshot!) ❌
RIGHT: browser → snapshot → act (ref from THAT snapshot) ✅
```

**Over-navigation — don't leave and come back when you can just re-snapshot:**
```
WRONG: Already on book page → navigate away → navigate back → snapshot  ❌
       (risks ERR_BLOCKED_BY_RESPONSE)
RIGHT: Already on book page → snapshot (get fresh refs for current page) ✅
```

**Wrapped errors — read the INNER error before giving up:**
```
WRONG: See "Can't reach browser control service" → tell user to restart  ❌
       (the inner error says "Element not found...Run a new snapshot")
RIGHT: Read inner error → recognize stale ref → re-snapshot → retry      ✅
```

---

## Workflow: Search and Get Details

Complete flow from search query to detailed book information.

```
1. browser → navigate → https://www.goodreads.com/search?q=<url-encoded-query>
2. browser → snapshot
3. Parse search results from snapshot (titles, authors, ratings)
4. Present top results to user
5. If user wants details on a specific book:
   a. browser → act → click on the book title ref from current snapshot
   b. browser → snapshot    ← MUST re-snapshot after navigation
   c. Parse book details (title, author, rating, description, reviews)
   d. If description is truncated:
      i.  browser → act → click "...more" ref
      ii. browser → snapshot    ← re-snapshot again
      iii. Parse full description
6. Present complete book details to user
```

## Workflow: Authentication Check

Verify whether the user is logged into Goodreads before auth-required actions.

```
1. browser → navigate → https://www.goodreads.com
2. browser → snapshot
3. Analyze snapshot for auth indicators:
   - LOGGED IN if: user profile name visible, "My Books" link present
   - LOGGED OUT if: "Sign In" button visible, "Join" call-to-action present
4. If LOGGED IN:
   → Proceed with the auth-required workflow
5. If LOGGED OUT:
   → Inform user: "You need to be logged into Goodreads. Please visit
     https://www.goodreads.com/user/sign_in and log in, then try again."
   → Optionally offer non-auth alternatives (genre browsing, public lists)
```

## Workflow: Add Book to "Want to Read" Shelf

```
1. If already on the target book's page (e.g., from a prior search/details lookup),
   skip navigation — just re-snapshot the current page for fresh refs.
   Otherwise, navigate to the book page (use Search workflow if needed).
2. browser → snapshot
3. Find the "Want to Read" button ref in the snapshot
4. browser → act → click on the "Want to Read" ref
5. browser → snapshot    ← re-snapshot to verify
6. Confirm to user:
   - Look for changed button state (e.g., checkmark, "Shelved" status)
   - If confirmation found: "Added '<Title>' to your Want to Read shelf!"
   - If unclear: use browser → screenshot to visually verify
   - If stale ref error: re-snapshot and retry — do NOT navigate away and back
```

## Workflow: Mark Book as Read with Rating

```
1. If already on the target book's page (e.g., from a prior search/details lookup),
   skip navigation — just re-snapshot the current page for fresh refs.
   Otherwise, navigate to the book page (use Search workflow if needed).
2. browser → snapshot
3. Find the shelf/status button or dropdown ref
4. browser → act → click to open status options
5. browser → snapshot    ← re-snapshot for updated refs
6. Find "Read" option ref
7. browser → act → click "Read" ref
8. browser → snapshot    ← re-snapshot again
9. Find star rating elements (look for rating stars or "Rate this book")
10. browser → act → click on the star corresponding to desired rating
    (e.g., 4th star for a 4/5 rating)
11. browser → snapshot    ← final verification
12. Confirm to user: "Marked '<Title>' as Read with a rating of <N>/5"
```

## Workflow: Expand Truncated Description

```
1. On a book detail page after snapshot
2. Look for "...more" or "Show more" ref in the description area
3. If found:
   a. browser → act → click on the "more" ref
   b. browser → snapshot    ← re-snapshot for full text
   c. Parse the now-expanded description
4. If not found:
   - Description may already be fully displayed
   - Or the expand control uses a different pattern — try browser → screenshot
     to visually inspect
```

## Workflow: Handle Pagination

For any list page (search results, shelves, genre pages) with multiple pages.

```
1. After parsing current page results
2. Look for pagination indicators in snapshot:
   - "Next" or "→" link ref
   - Page number refs (1, 2, 3, ...)
   - "Showing X-Y of Z results"
3. If more pages needed:
   a. Option A: Click "Next" ref
      - browser → act → click "Next" ref
      - browser → snapshot    ← re-snapshot
   b. Option B: Navigate directly
      - browser → navigate → append ?page=<N> to current URL
      - browser → snapshot
4. Parse and accumulate results from the new page
5. Repeat as needed (be mindful of not loading too many pages)
```

## Workflow: Browse Recommendations (Authenticated)

```
1. Run Authentication Check workflow
2. If logged in:
   a. browser → navigate → https://www.goodreads.com/recommendations
   b. browser → snapshot
   c. Parse recommendation groups:
      - Look for "Because you liked <Book>" headers
      - Under each, extract recommended book titles, authors, ratings
   d. Present recommendations grouped by source
3. If more recommendations exist:
   - Look for "Show more" or pagination
   - Follow Pagination workflow
```

## Workflow: Browse Recommendations (Unauthenticated Fallback)

When the user is not logged in, offer alternative discovery paths.

```
1. Ask user for a genre or interest
2. browser → navigate → https://www.goodreads.com/genres/<genre>
3. browser → snapshot
4. Parse "Most Popular" and "New Releases" sections
5. Present curated results to user

Alternative:
1. browser → navigate → https://www.goodreads.com/list/popular_lists
2. browser → snapshot
3. Parse popular list titles and descriptions
4. Let user pick a list to explore
5. browser → act → click on chosen list ref
6. browser → snapshot    ← re-snapshot
7. Parse and present list contents
```

## Workflow: View User's Shelf

```
1. Run Authentication Check workflow
2. If logged in:
   a. browser → snapshot (on Goodreads homepage)
   b. Find "My Books" link ref
   c. browser → act → click "My Books" ref
   d. browser → snapshot    ← re-snapshot
   e. Parse shelf contents: book titles, ratings, dates
   f. To switch shelves:
      - Find shelf tab refs ("Read", "Currently Reading", "Want to Read")
      - browser → act → click desired shelf ref
      - browser → snapshot    ← re-snapshot
      - Parse updated shelf contents
```

## General Tips

- **Always re-snapshot after any navigation or click that changes the page.** This is the single most important rule.
- **When in doubt, screenshot.** If snapshot output is confusing, take a screenshot to see the actual visual state.
- **Don't over-paginate.** For search results, 2-3 pages is usually sufficient. Ask the user before loading more.
- **Cache nothing.** Refs, page state, and content can change at any time. Always work with fresh snapshots.
- **Be explicit in confirmations.** After shelf actions, always re-snapshot to verify the action took effect.


path: references/URLS.md
content: # Goodreads URL Patterns

Reference for all Goodreads URL patterns used by this skill.

**Base URL:** `https://www.goodreads.com`

## Search

| Pattern | Description | Example |
|---------|-------------|---------|
| `/search?q=<query>` | General search (books, authors, etc.) | `/search?q=dune` |
| `/search?q=<query>&search_type=books` | Books only | `/search?q=dune&search_type=books` |
| `/search?q=<query>&search_type=authors` | Authors only | `/search?q=frank+herbert&search_type=authors` |

**URL encoding tips:**

- Spaces → `+` or `%20` (both work)
- Ampersand → `%26`
- Quotes → `%22`
- Apostrophes → `%27`
- Colons → `%3A`

## Book Pages

| Pattern | Description | Example |
|---------|-------------|---------|
| `/book/show/<id>` | Book by numeric ID | `/book/show/234225` |
| `/book/show/<id>.<slug>` | Book with SEO slug | `/book/show/234225.Dune` |
| `/book/show/<id>-<slug>` | Alternative slug format | `/book/show/234225-dune` |

Book IDs are stable numeric identifiers. The slug portion is optional and ignored by Goodreads — only the numeric ID matters.

## Author Pages

| Pattern | Description | Example |
|---------|-------------|---------|
| `/author/show/<id>.<name>` | Author profile | `/author/show/58.Frank_Herbert` |
| `/author/list/<id>.<name>` | Author's book list | `/author/list/58.Frank_Herbert` |

## User Shelves & Reading Lists

| Pattern | Description | Example |
|---------|-------------|---------|
| `/review/list/<user_id>` | User's default shelf | `/review/list/12345678` |
| `/review/list/<user_id>?shelf=read` | "Read" shelf | `/review/list/12345678?shelf=read` |
| `/review/list/<user_id>?shelf=currently-reading` | "Currently Reading" shelf | `/review/list/12345678?shelf=currently-reading` |
| `/review/list/<user_id>?shelf=to-read` | "Want to Read" shelf | `/review/list/12345678?shelf=to-read` |
| `/review/list/<user_id>?shelf=<custom>` | Custom shelf | `/review/list/12345678?shelf=favorites` |

**Note:** User ID is required to view shelves. The logged-in user's shelves can be accessed via the "My Books" link in the navigation.

## Recommendations

| Pattern | Description | Auth Required |
|---------|-------------|---------------|
| `/recommendations` | Personalized recommendations | Yes |
| `/recommendations/genre/<genre>` | Genre-based recommendations | Yes |

## Genres & Lists

| Pattern | Description | Auth Required |
|---------|-------------|---------------|
| `/genres/<genre>` | Genre page | No |
| `/genres/list` | All genres | No |
| `/list/popular_lists` | Popular book lists | No |
| `/list/show/<id>` | Specific list | No |
| `/list/best_of_year/<year>` | Best of year lists | No |

**Common genre slugs:** `fiction`, `non-fiction`, `mystery`, `science-fiction`, `fantasy`, `romance`, `thriller`, `historical-fiction`, `horror`, `biography`

## Authentication

| Pattern | Description |
|---------|-------------|
| `/user/sign_in` | Login page |
| `/user/sign_up` | Registration page |

## Pagination

Most list pages support pagination via query parameter:

- `?page=<n>` — Page number (1-indexed)
- Example: `/search?q=dune&page=2`

Can be combined with other query params: `/review/list/12345678?shelf=read&page=2`


path: references/SELECTORS.md
content: # Goodreads Page Structure & Selectors

Reference for identifying content in `browser` → `snapshot` output. Since Goodreads uses dynamic rendering, look for **text patterns and keywords** rather than CSS selectors.

## General Navigation (All Pages)

**Logged-in indicators** (present in snapshot when authenticated):

- User's display name in the navigation area
- "My Books" link
- "Browse" dropdown
- Notification bell / inbox icon references

**Logged-out indicators:**

- "Sign In" link/button
- "Join" link/button
- Prominent call-to-action for registration

## Search Results Page

**URL:** `/search?q=<query>`

**Content patterns in snapshot:**

```
Search results for "<query>"

<Book Title>                    ← Clickable link (has a ref)
by <Author Name>                ← Clickable link (has a ref)
<avg rating> avg rating — <N> ratings — published <year>
```

**Key anchors to look for:**

- `"Search results for"` — confirms you're on the search page
- `"by "` — precedes author name
- `"avg rating"` — precedes rating count
- `"ratings"` — follows rating number
- `"published"` — precedes publication year
- `"Showing <N> of <total>"` or pagination indicators

**No results pattern:**

- `"No results"` or `"0 results"`
- Suggestion text like `"Try searching for..."`

## Book Detail Page

**URL:** `/book/show/<id>`

**Content patterns in snapshot:**

```
<Book Title>
by <Author Name>

<rating value>                  ← e.g., "4.28"
<N> ratings                     ← e.g., "1,234,567 ratings"
<N> reviews                     ← e.g., "45,678 reviews"

<Description text>
...more                         ← Clickable ref to expand truncated descriptions

<N> pages, <format>             ← e.g., "412 pages, Paperback"
Published <date>                ← e.g., "Published August 1, 2005"

Genres:
<genre links>                   ← Clickable refs
```

**Key anchors to look for:**

- `"by "` — precedes author (clickable link)
- `"ratings"` — near the numeric rating value
- `"reviews"` — near the review count
- `"...more"` or `"Show more"` — truncated description expander
- `"pages"` — near page count
- `"Published"` — precedes publication date
- `"Genres"` or genre-like section — lists genres/shelves

**Shelf/Action buttons:**

- `"Want to Read"` — primary shelving button
- `"Currently Reading"` — status option
- `"Read"` — status option
- Star/rating indicators — for rating the book
- `"Write a review"` — review prompt

**Community reviews section:**

- `"Community Reviews"` header
- Individual reviews with rating stars, reviewer name, review text
- `"See all reviews"` or pagination for more reviews

## Recommendations Page

**URL:** `/recommendations`

**Content patterns in snapshot:**

```
Recommendations

Because you liked <Book Title>:
  <Recommended Book Title>      ← Clickable link
  by <Author Name>
  <rating> avg rating
```

**Key anchors:**

- `"Recommendations"` — page header
- `"Because you liked"` — recommendation reason
- `"Based on your"` — alternative recommendation context
- `"avg rating"` — rating for recommended book

**If not logged in:**

- Redirect to sign-in page
- Look for `"Sign In"` or `"sign_in"` in the URL

## User Shelf Page

**URL:** `/review/list/<user_id>?shelf=<shelf>`

**Content patterns in snapshot:**

```
<User Name>'s books

<shelf_name> (<count>)          ← Shelf tabs/links

<Book Title>                    ← Clickable link
<Author Name>
<user's rating>
<date read / date added>
```

**Key anchors:**

- Shelf name and count in parentheses
- `"date read"` or `"date added"` columns
- `"remove"` or shelf-change options per book
- Pagination indicators for large shelves

## Genre Page

**URL:** `/genres/<genre>`

**Content patterns in snapshot:**

```
<Genre Name> Books

Most Popular <Genre> Books
  <Book Title>                  ← Clickable link
  by <Author Name>
  <rating> avg rating — <N> ratings

New Releases in <Genre>
  ...
```

**Key anchors:**

- `"Most Popular"` — popular books section
- `"New Releases"` — recent additions
- `"avg rating"` — rating indicator

## Tips for Snapshot Parsing

1. **Ratings** are typically decimal numbers near the word "rating" or "ratings" (e.g., `4.28 avg rating`)
2. **Counts** use comma separators (e.g., `1,234,567 ratings`)
3. **Clickable elements** have ref numbers in the snapshot — these are what you pass to `act`
4. **Truncated text** often ends with `...more` or `...` followed by a clickable ref
5. **Multi-section pages** have clear header patterns to delineate sections


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)