carrick-census

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:

{
  "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 details the execution model shared by all four skills.
• MCP tools documents search_by_intent and multi-phrasing query arguments.