Shoehorn

Activity logging that answers who did what, to which entity, when — plus one good question asked at the moment someone can answer it. Shoehorn reads a brief about your app and writes the implementation prompt. Your coding agent does the rest.
Your code never comes here. Only the brief you paste, and it is stored privately — never in a public gallery.
Run this in your own coding agent

It only reads. Nothing is modified, and nothing leaves your machine except the JSON it prints.
You are inspecting this codebase to prepare an Activity Logging Brief. Your job is analysis only — do not modify any files, do not implement anything.

## What opinionated activity logging means

You are identifying DOMAIN ACTIONS, not UI events:
✓ INCLUDE: goal.created, invoice.sent, member.invited, report.exported, subscription.cancelled
✗ EXCLUDE: button.tapped, screen.viewed, modal.opened, input.focused, tab.changed

Every logged event must answer: "Who did what, to which entity, when?" If it doesn't, it's noise.

## How to inspect

Work through the codebase in this order before writing the JSON:

1. Read the README, pubspec.yaml / package.json / Gemfile / requirements.txt (whichever applies) and any high-level docs to establish app purpose, language, and framework.
2. Identify the backend and database: Supabase, Firebase/Firestore, a custom REST API, Rails, Django, etc.
3. Enumerate all data models or database tables. For each: what entity is it? Which of create/update/delete/status_change operations actually exist in the codebase (routes, mutations, server actions, API calls, repository methods)?
4. Trace multi-step user flows: onboarding, core creation flows, publishing, checkout, deletion. For each flow identify: the single event that starts it (entryEvent), the single event that marks successful completion (successEvent), and how to detect abandonment (e.g. "user returns after 24h without firing successEvent").
5. Find the auth setup: provider, session model, how user identity is passed to the backend.
5a. Locate the browser-side data client: find the file that creates and exports the Supabase/Firebase client for use in browser/client-side code (search for `createBrowserClient`, `createClient`, or similar near the backend SDK import). Note the exact import path to use within the project (e.g. `@/lib/supabase/client`), and the env var names it references for the URL and the public/anon key.
6. Determine the access model — who needs to see the captured data:
   - "personal" — only the logged-in user sees their own activity (e.g. a personal habit tracker, a single-tenant tool)
   - "admin" — the developer or product owner needs to see all users' activity for product insight; no support staff involved
   - "support" — a customer support team needs to look up specific users' activity to help them; that access must itself be logged for audit purposes
   Identify which user roles (from step 4 / the codebase's role model) map to admin or support access.
7. Search for any existing logging, analytics, or tracking calls. Note what's there.
8. Derive candidate events: for each entity × operation pair that matters, name the event in dot-notation (entity.verb). Keep only actions that signal intent or completion — not state reads or navigation.
   Also: for each multi-step flow identified in step 4, include a milestone event for each meaningful checkpoint — not just the final outcome. These are domain state changes (e.g. onboarding.profile_created, onboarding.first_project_created) not UI interactions (e.g. onboarding.next_clicked). Milestone events enable funnel drop-off analysis without adding noise.
9. Identify 2–4 distinct user types based on behavioural differences. Think: who uses the core flow repeatedly vs. who tries it once? Who reaches the success event vs. who drops off midway? Who pays vs. who explores freely? For each type, describe what distinguishes them behaviourally (not demographically) and which events signal membership.

10. Identify feedback opportunities — the specific moments where a targeted one-question prompt would be most valuable:
   - Friction: after a validation error, after the second failed attempt at something, when a multi-step flow is abandoned
   - First success: first time a key flow completes (first item created, first invite sent, first export)
   - Confusion risk: transition points where the user may not know what happens next
   - Completion: end of a significant multi-step flow

## Output format

Return ONLY a valid JSON object matching the schema below. No markdown fences, no commentary, no explanation — just the JSON.

Verify before returning: all action names are dot-notation entity.verb, operations arrays contain only operations that actually exist, feedbackOpportunities have a specific moment description (not a generic phrase), candidateEvents has 5–15 items, app.language / app.backend accurately reflect the codebase, accessModel.scenario is one of personal / admin / support, and backendClient.browserClientPath is a valid import path found in the codebase.

{
  "app": {
    "name": "string — the app name as it appears in the codebase",
    "purpose": "string — one sentence: what the app does and for whom",
    "framework": "string — e.g. 'next', 'flutter', 'react-native', 'vue', 'nuxt', 'rails', 'django', 'sveltekit', 'remix'",
    "language": "string — primary language: 'typescript', 'javascript', 'dart', 'python', 'ruby', 'swift', 'kotlin', 'go'",
    "backend": "string — where data is stored: 'supabase', 'firebase', 'custom-api', 'rails', 'django', 'laravel', 'convex', 'appwrite', or describe it"
  },
  "userRoles": [
    "string — each distinct role, e.g. 'owner', 'member', 'admin', 'viewer'"
  ],
  "accessModel": {
    "scenario": "string — one of: personal, admin, support",
    "adminRoles": ["string — role names that need full cross-user read access, e.g. 'admin', 'superuser'. Empty array if personal."],
    "supportRoles": ["string — role names that need per-user read access with audit logging, e.g. 'support', 'cs_agent'. Empty array unless support scenario."]
  },
  "entities": [
    {
      "name": "string — singular entity name matching the codebase, e.g. 'goal', 'invoice', 'workspace'",
      "operations": ["string — ONLY operations that actually exist in this codebase: 'create', 'update', 'delete', 'status_change'"]
    }
  ],
  "flows": [
    {
      "name": "string — snake_case, e.g. 'goal_creation', 'member_onboarding', 'checkout'",
      "description": "string — one sentence: what this flow achieves for the user",
      "entryEvent": "string — dot-notation event that starts the flow, e.g. 'user.signed_up'",
      "successEvent": "string — dot-notation event that marks successful completion, e.g. 'project.created'",
      "steps": ["string — ordered domain events (dot-notation) from entry to success"],
      "abandonSignal": "string — how to detect abandonment, e.g. 'user returns after 24h without firing successEvent'"
    }
  ],
  "userTypes": [
    {
      "name": "string — short archetype name, e.g. 'Power User', 'Casual Browser', 'Free Explorer'",
      "description": "string — one sentence: what distinguishes this type behaviourally",
      "signals": ["string — dot-notation events or count patterns that indicate membership, e.g. 'project.kit_copied fired more than once', 'user never fires project.unlocked'"]
    }
  ],
  "dbModel": "string — one sentence: main tables/collections and the key relationships between them",
  "authModel": "string — one sentence: provider (e.g. Supabase Auth, Firebase Auth, Clerk, Devise), session type, and how user identity is scoped to data",
  "backendClient": {
    "browserClientPath": "string — import path to the browser client module, e.g. '@/lib/supabase/client' or '@/utils/firebase'. Omit if not Supabase/Firebase.",
    "urlEnvVar": "string — env var name for the backend URL, e.g. 'NEXT_PUBLIC_SUPABASE_URL'",
    "keyEnvVar": "string — env var name for the anon/publishable key, e.g. 'NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY'"
  },
  "existingLogging": "string — one sentence: what is currently tracked and where (console, Mixpanel, Firebase Analytics, etc.), or 'none'",
  "candidateEvents": [
    {
      "action": "string — dot-notation entity.verb, e.g. 'goal.created', 'invoice.sent', 'search.abandoned'",
      "entity": "string — the entity name (singular)",
      "why": "string — one sentence: what product question this event answers or what behaviour it signals"
    }
  ],
  "feedbackOpportunities": [
    {
      "context": "string — the specific moment, e.g. 'immediately after the user completes their first goal' or 'when a payment fails for the second time'",
      "question": "string — the exact question to show the user at that moment"
    }
  ],
  "openQuestions": [
    "string — anything ambiguous that would affect the logging design, e.g. 'Goals can be private or public — should visibility changes log as status_change?'"
  ]
}
8,490 characters
Paste what it printed

The whole JSON object, from the first brace to the last.