`carrick-census` locates every implementation of a specific concept across your project by executing dual semantic searches against the intent index—evaluating both why the code exists (purpose) and how it is implemented (mechanism)—and merging the results into a deduplicated audit report.

## Invocation triggers

Agents load `carrick-census` when answering exhaustive discovery questions:

- Every service that reads a specific environment variable
- Every route handler that verifies user authentication or permissions
- Every consumer subscribing to a specific message queue or topic

## Tool sequence

1. **Execute dual-phrased search**:
   - `search_by_intent(query, also_phrased_as: ["<mechanism>"], compact: true, top_k: 20)`: Searches for both the functional purpose and technical mechanism.
2. **Page through all results**:
   - Re-invoke `search_by_intent` with `offset: next_offset` until `has_more` is false.
   - `compact: true` returns lightweight locators (`name`, `file_path`, `line_number`, `similarity`).
3. **Merge and deduplicate**:
   - When servers do not support `also_phrased_as`, the skill executes both queries sequentially and joins the result sets on `file_path` and `line_number`.

## Report structure and receipts

Reports begin with a search receipt documenting query coverage:

- **Rows read**: Total rows paged through during execution.
- **`total_candidates`**: Total matching candidates in the ranked index.
- **`hidden_by_threshold`**: Count of candidates omitted below the similarity floor along with the highest-scoring omitted function.
- **`total_without_intent`**: Functions lacking generated intent text.
- **`total_without_intent_by_design`**: How many of those the scan was never going to describe, such as single-line utilities. The rest is what a later scan fills in.
- **`total_intent_carried_forward`**: Intent descriptions preserved from prior scan commits.

Below the receipt, the skill formats matches into a census table recording the function, location, intent summary, and discovery phrasing (`purpose`, `mechanism`, or `both`).

## Coverage boundaries

- **Working tree modifications**: The intent index reflects the default branch in CI. Functions added on unmerged local branches do not appear in census results.
- **Non-function code**: The index tracks declared functions and class methods. Direct module-level code, standalone configuration files, and templates are omitted from intent searches.
- **Route handlers with shared implementations**: A function acting as a shared middleware or helper may appear in results even if it is not the primary handler for the targeted route.

## Example

Executing a dual-phrased query:

```json
{
  "query": "check the API key on an incoming request",
  "phrasings": [
    "check the API key on an incoming request",
    "hash a bearer token and read the stored key row from the table"
  ],
  "hidden_by_threshold": {
    "count": 56,
    "best": {
      "name": "routeHandlerKeys",
      "file_path": "functions/orders/route_handlers.js",
      "line_number": 101
    }
  },
  "results": [
    {
      "name": "validateApiKey",
      "file_path": "functions/shared/verify_api_key.js",
      "line_number": 212,
      "end_line": 214,
      "retrieved_by": "both",
      "matched_phrasings": [0],
      "role": "helper: no indexed operation or recorded call inside its line span"
    },
    {
      "name": "readSessionRow",
      "file_path": "app/src/lib/session-store.ts",
      "line_number": 157,
      "end_line": 167,
      "retrieved_by": "both",
      "matched_phrasings": [1],
      "role": "helper: no indexed operation or recorded call inside its line span"
    },
    {
      "name": "requireAccountAccess",
      "file_path": "functions/gateway/src/handler.ts",
      "line_number": 94,
      "end_line": 140,
      "retrieved_by": "lexical",
      "matched_phrasings": [0, 1],
      "role": "route file: declares DELETE /v1/sessions (acme-gateway), GET /v1/sessions (acme-gateway), +2 more; the indexed handler rows are outside this function's span"
    }
  ]
}
```

The skill inspects the identified lines in source code and outputs the census report:

| file:line | function | what it does | found by |
| :--- | :--- | :--- | :--- |
| functions/shared/verify_api_key.js:212 | validateApiKey | resolves a presented key through the default lookup | purpose |
| app/src/lib/session-store.ts:157 | readSessionRow | reads one session's row back from the table | mechanism |
| functions/gateway/src/handler.ts:94 | requireAccountAccess | admits a request to an account, or refuses it | both |

## Related

- [Task skills](/task-skills) details the execution model shared by all four skills.
- [MCP tools](/mcp-tools) documents `search_by_intent` and multi-phrasing query arguments.