couchdb-investigate

name	couchdb-investigate
description	Use for read-only CouchDB investigations that combine database records, current repository code, and reusable analytics/query recipes.

CouchDB Investigation

Use this skill when the user asks to answer a question that mixes CouchDB data with code in the current repository.

Workflow

1. Check available profiles with profile_active and profile_list. Stop if no active profile is configured.
2. Ask recipe_suggest with the user's original request. Reuse matching recipes as hints, not as proof.
3. Inspect relevant repository code with normal Codex file/search tools before querying CouchDB when the request mentions encoding, decoding, ID derivation, address derivation, or frontend/backend helper logic.
4. Use targeted read-only CouchDB tools:
   • Prefer doc_head_or_exists when checking likely document IDs.
   • Use doc_get for known documents.
   • Use mango_find for selectors.
   • Use view_query for known design views.
   • Use raw_get only for CouchDB-relative endpoints that are not covered by the structured tools.
5. Keep result limits conservative. Increase a limit only when the user's question requires it.
6. Cross-reference database fields with the code path that produces or decodes them. State which parts came from code and which came from CouchDB.
7. If the investigation produces a reusable pattern, call recipe_save with only workflow metadata: databases, selectors or view names in prose, code anchors, and steps. Never store returned user records, secrets, or payload bodies as recipe memory.

Safety Boundaries

• Do not perform writes, deletes, compaction, replication, or admin actions.
• Do not paste credentials into prompts, recipes, command output, or files.
• Treat saved recipes as suggestions. Always re-read live CouchDB data for the actual answer.
• If a query result is truncated, say so and either answer from the available subset or run a narrower query.

Output Shape

For user-facing answers, include:

• Short answer.
• Evidence from CouchDB records, with database/document identifiers where useful.
• Code references used to derive or decode values.
• Any limits, truncation, or uncertainty.