## TL;DR

URL-encode every path parameter before inserting it into the URL, and the lookups work. An unencoded @ in a path breaks routing; encoded as %40 it travels safely.

Encode at the boundary where the parameter enters the URL, in one helper, so no call site can forget it.

## Verbatim query

```text
agent didn't URL-encode path parameters  -  emails used as IDs broke every user-lookup call
```

## Steps

1. Reproduce with a raw email in the path
   Build the lookup URL with the email unencoded and log the full URL.
   Send it and record the failure - 404, 400, or a wrong-user response.
   Expected: The unencoded URL visibly contains the raw @ and the call fails.

2. Verify the encoded version works
   Encode the email and resend the identical lookup.
   Confirm the correct user record comes back.
   Expected: The encoded URL returns the right user, proving encoding was the issue.

3. Add a path-encoding helper
   Write one function that encodes a single path segment and nothing else.
   Use it for every parameter interpolated into a path.
   Expected: All path parameters pass through the encoder.

4. Audit every path interpolation
   Search for URL building with format strings or concatenation that inserts variables.
   Route each through the helper.
   Expected: No raw variable lands in a path anywhere in the client.

5. Add an encoding test
   Test that an email ID produces a URL with %40 and no raw @.
   Include + and spaces in the test cases.
   Expected: The test passes and would catch a regen that drops encoding.

## Use this when

- User lookups by email or other special-character IDs fail
- The logged URL contains raw @ or + in the path
- Lookups work for simple numeric IDs but break for email IDs

## Not for this skill when

- The path is encoded and lookups still fail - the ID value itself may be wrong
- Failures are in query parameters, not the path - check query encoding separately
- The API expects the raw email in the path by design - rare, but check the docs

## Variant phrasings

### email as path parameter breaks
Emails contain @ and + and dots; paths treat those as structural characters unless encoded.

### unencoded path parameter 404
A raw @ in a path can split routing in surprising ways on strict servers.

### URL encode path segments
Encode each segment individually - encoding the whole URL double-encodes the slashes.

## Why it happens

URLs have structure: slashes separate segments, @ separates userinfo, + means space in queries. An email dropped raw into a path collides with that structure, so the server parses a different path than you intended. Encoding translates the email's special characters into safe sequences the server decodes back after routing. The fix belongs in one helper because every call site will otherwise forget it eventually.

## Edge cases

- Encode segments, not the whole URL: encoding the full URL turns real slashes into %2F and breaks routing
- Some frameworks encode path params automatically - know whether yours does before adding a second layer
- Double encoding (%2540) is the tell that two layers both encoded; decode once or encode once, not both

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_J9H7l7zmg8nfhZ9hkTxDpQ