{"id":"e84a70b9-e62b-4d8e-9af3-a5ff066dd58d","entityType":"agent","slug":"clawhub-kaicianflone-pronoun-resolver","name":"Coding Pronoun Prompt Resolver","canonicalUrl":"https://www.xpersona.co/agent/clawhub-kaicianflone-pronoun-resolver","canonicalPath":"/agent/clawhub-kaicianflone-pronoun-resolver","generatedAt":"2026-10-11T20:59:39.941Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-11T16:57:57.727Z","emptyReason":null},"description":"Detects ambiguous pronouns, vague referents, and bare imperatives in user messages and flags them for resolution using conversation context. Zero-latency det... Skill: Coding Pronoun Prompt Resolver Owner: kaicianflone Summary: Detects ambiguous pronouns, vague referents, and bare imperatives in user messages and flags them for resolution using conversation context. Zero-latency det... Tags: latest:0.11.0 Version history: v0.11.0 | 2026-05-31T16:09:22.001Z | user Always-on logging directive + locked, sanitizing ledger writer (bin/log-resolution.py). Secret/PII redaction, hex","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1K downloads reported by the source. Last updated 10/11/2026.","installCommand":"clawhub skill install s173yh69sk2g7jzav29e74412s83qaga:pronoun-resolver","sourceUrl":"https://clawhub.ai/kaicianflone/pronoun-resolver","homepage":"https://clawhub.ai/kaicianflone/skills/pronoun-resolver","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/kaicianflone/pronoun-resolver","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/kaicianflone/skills/pronoun-resolver","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":60,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Detects ambiguous pronouns, vague referents, and bare imperatives in user messages and flags them for resolution using conversation context. Zero-latency det..."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-11T16:57:57.727Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T16:57:57.727Z","emptyReason":null},"stars":null,"forks":null,"downloads":1023,"packageName":null,"latestVersion":"0.11.0","tractionLabel":"1K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T16:57:57.665Z","emptyReason":null},"lastUpdatedAt":"2026-10-11T16:57:57.727Z","lastCrawledAt":"2026-10-11T16:57:57.665Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-12T16:57:57.665Z","lastVerifiedAt":null,"highlights":[{"version":"0.11.0","createdAt":"2026-05-31T16:09:22.001Z","changelog":"Always-on logging directive + locked, sanitizing ledger writer (bin/log-resolution.py). Secret/PII redaction, hex-validated prompt_hash, flock concurrency fix, corruption-safe writes. Adds unit tests. (Claude+Codex adversarial review)","fileCount":13,"zipByteSize":27122},{"version":"0.10.0","createdAt":"2026-05-26T02:39:21.768Z","changelog":"- Adds per-message analytics via new stats script (`bin/stats.py`) and `.claude/pronoun-resolver-analytics.jsonl` log. - Updates ledger to store prompt hashes instead of raw prompt text for improved privacy. - Documents new `--stats` argument to run analytics and output results. - Expands capabilities and data retention details in skill manifest for better transparency.","fileCount":10,"zipByteSize":17278},{"version":"0.9.1","createdAt":"2026-05-25T15:41:50.230Z","changelog":"v0.9.1: Zero-latency hook architecture. Removes all LLM calls. Smart demonstrative filtering. Bare imperative detection. Contraction-aware. Claude resolves using conversation context.","fileCount":8,"zipByteSize":14385},{"version":"0.9.0","createdAt":"2026-05-24T07:09:18.120Z","changelog":"Eval framework (10 cases), resolve.py extraction, adversarial review fixes (stdin guard, fence stripping, sed injection, backtick matching)","fileCount":13,"zipByteSize":19123},{"version":"0.1.0","createdAt":"2026-05-24T06:44:29.173Z","changelog":"Initial release: tiered LLM resolution engine with self-learning ledger","fileCount":9,"zipByteSize":12624}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s173yh69sk2g7jzav29e74412s83qaga:pronoun-resolver","setupComplexity":"low","setupSteps":["Setup complexity is LOW. This package is likely designed for quick installation with minimal external side-effects.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-kaicianflone-pronoun-resolver/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-kaicianflone-pronoun-resolver/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-kaicianflone-pronoun-resolver/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-kaicianflone-pronoun-resolver/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-kaicianflone-pronoun-resolver/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-kaicianflone-pronoun-resolver/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-11T20:59:39.938Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-kaicianflone-pronoun-resolver/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-kaicianflone-pronoun-resolver/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-kaicianflone-pronoun-resolver/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-kaicianflone-pronoun-resolver/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-11T16:57:57.727Z","emptyReason":null},"readme":"Skill: Coding Pronoun Prompt Resolver\n\nOwner: kaicianflone\n\nSummary: Detects ambiguous pronouns, vague referents, and bare imperatives in user messages and flags them for resolution using conversation context. Zero-latency det...\n\nTags: latest:0.11.0\n\nVersion history:\n\nv0.11.0 | 2026-05-31T16:09:22.001Z | user\n\nAlways-on logging directive + locked, sanitizing ledger writer (bin/log-resolution.py). Secret/PII redaction, hex-validated prompt_hash, flock concurrency fix, corruption-safe writes. Adds unit tests. (Claude+Codex adversarial review)\n\nv0.10.0 | 2026-05-26T02:39:21.768Z | auto\n\n- Adds per-message analytics via new stats script (`bin/stats.py`) and `.claude/pronoun-resolver-analytics.jsonl` log.\n- Updates ledger to store prompt hashes instead of raw prompt text for improved privacy.\n- Documents new `--stats` argument to run analytics and output results.\n- Expands capabilities and data retention details in skill manifest for better transparency.\n\nv0.9.1 | 2026-05-25T15:41:50.230Z | user\n\nv0.9.1: Zero-latency hook architecture. Removes all LLM calls. Smart demonstrative filtering. Bare imperative detection. Contraction-aware. Claude resolves using conversation context.\n\nv0.9.0 | 2026-05-24T07:09:18.120Z | user\n\nEval framework (10 cases), resolve.py extraction, adversarial review fixes (stdin guard, fence stripping, sed injection, backtick matching)\n\nv0.1.0 | 2026-05-24T06:44:29.173Z | user\n\nInitial release: tiered LLM resolution engine with self-learning ledger\n\nArchive index:\n\nArchive v0.11.0: 13 files, 27122 bytes\n\nFiles: bin/detect-implicit.py (2607b), bin/detect-pronouns.sh (6359b), bin/log-resolution.py (9122b), bin/stats.py (1801b), CHANGELOG.md (1871b), evals/cases.json (6651b), evals/results.json (4242b), evals/run_evals.py (11868b), README.md (8437b), skill-card.md (2451b), SKILL.md (5793b), tests/test_log_resolution.py (5243b), _meta.json (136b)\n\nFile v0.11.0:SKILL.md\n\n---\nname: pronoun-resolver\nversion: 0.11.0\ndescription: |\n  Detects ambiguous pronouns, vague referents, and bare imperatives in user messages\n  and flags them for resolution using conversation context. Zero-latency detection via\n  hook; resolution happens inside the conversation where context lives. Self-learning\n  via correction ledger with adaptive confidence tiering.\ncapabilities:\n  - user-prompt-submit hook (fires on every message, regex-only, no LLM calls)\n  - file-write: ~/.claude/skills/pronoun-resolver/.claude/pronoun-ledger.json (resolution metadata, no raw prompts)\n  - file-write: ~/.claude/skills/pronoun-resolver/.claude/pronoun-resolver-analytics.jsonl (per-message stats)\ndata_retention: |\n  All data is local-only, never transmitted externally. Prompts are hashed (SHA-256),\n  never stored as text. Both data files can be deleted without affecting functionality.\nhooks:\n  user-prompt-submit:\n    - type: command\n      command: \"bash ${CLAUDE_SKILL_DIR}/bin/detect-pronouns.sh\"\n      statusMessage: \"Scanning for ambiguous references...\"\n---\n\n# Pronoun Resolver\n\n## Arguments\n\nIf invoked with `--stats`: run `python3 ~/.claude/skills/pronoun-resolver/bin/stats.py` and display the output. Do not proceed with the rest of this skill.\n\n---\n\nYou are operating with the pronoun resolver active. When the hook detects ambiguous\nreferences in a user message, you will see flags injected before the message.\n\n## Your Role\n\nYOU are the resolver. You have the conversation context. The hook just detects — you decide.\n\n## Resolution Tiering\n\nWhen you see `[AMBIGUOUS:]` flags, apply this framework:\n\n### GREEN — Resolve silently (90%+ confidence)\nThe referent is obvious from the last 1-3 messages. Just act. Don't mention the resolution.\n- \"Fix it\" when you just showed them a bug → fix the bug\n- \"Make that work\" after discussing a failing test → fix the test\n\n### YELLOW — State assumption, proceed (70-90% confidence)\nYou're fairly sure but there's ambiguity. State what you're assuming in one line, then act.\n- \"I'm taking 'the other one' to mean `auth.ts` since we discussed two files. Acting on that.\"\n\n### RED — Ask before acting (<70% confidence)\nMultiple plausible referents, or no recent context to resolve against. Ask concisely.\n- \"What should I make good — the UI layout we discussed or the API response format?\"\n\n### BLACK — Bare imperative, no context at all\nFirst message of a conversation with no object. Always ask.\n- \"Make good\" with no prior context → \"What would you like me to improve?\"\n\n## Flag Format\n\nThe hook outputs a preamble followed by flags:\n```\n[PRONOUN-RESOLVER: Resolve these using conversation context. HIGH confidence=act silently. MEDIUM=state assumption then act. LOW/no context=ask user first.]\n[AMBIGUOUS: pronouns=\"it,that\" | type=pronoun]\n[AMBIGUOUS: vague=\"other,something\" | type=vague_referent]\n[AMBIGUOUS: implicit verb=\"make\" | type=bare_imperative | subtype=verb_adjective]\n```\n\n## Ledger\n\nResolution accuracy is tracked at `~/.claude/skills/pronoun-resolver/.claude/pronoun-ledger.json`.\nWhen you resolve an ambiguous reference, log it. When the user corrects you\n(\"no not that\", \"I meant X\"), mark the previous resolution as corrected.\n\n**The hook injects a `[PRONOUN-RESOLVER-LOG: ...]` directive on every fire** with the exact\n`bin/log-resolution.py` command and ledger path, so the logging instruction is present even\nwhen this SKILL.md isn't loaded into context (the hook prints it; you run the command). Use that helper rather than hand-editing the JSON — it\ndoes an atomic read-modify-write and keeps `resolution_count` in sync. Do **not** log when\nyou couldn't resolve (asked the user, false-positive flag, or no real referent).\n\nThe ledger schema:\n```json\n{\n  \"resolutions\": [...],\n  \"resolution_count\": 0,\n  \"adaptive_threshold\": 0.8,\n  \"context_reliability\": {}\n}\n```\n\nEach resolution entry:\n```json\n{\n  \"timestamp\": \"ISO8601\",\n  \"pronoun\": \"it\",\n  \"prompt_hash\": \"sha256 hex of the full prompt (no raw text stored)\",\n  \"resolved_to\": \"the auth middleware\",\n  \"tier_used\": \"green|yellow|red|black\",\n  \"confidence\": 0.92,\n  \"was_corrected\": false\n}\n```\n\nNever store raw prompt text in the ledger. Use `prompt_hash` for deduplication only.\n\n## Correction Detection\n\nIf the user's next message corrects your resolution:\n1. Mark the previous ledger entry as `was_corrected: true`\n2. Adjust your confidence calibration — if you're frequently wrong at a given tier, escalate more\n\n## Adaptation\n\nEvery 10 resolutions, check your accuracy:\n- If >90% correct at green tier → you're well calibrated\n- If <75% correct → shift toward yellow/red (ask more often)\n- Track which context signals (last edited file, recent discussion topic, etc.) are most reliable\n\n## Disable\n\nIf the user creates `.claude/pronoun-resolver-disabled` in the project root, stop resolving.\n\n## What Gets Detected\n\n1. **Personal pronouns** (always flagged): it, them, they, its\n2. **Demonstratives** (flagged only when standalone, not as determiners): this, that, these, those\n   - \"fix this\" → flagged (\"this\" is standalone pronoun)\n   - \"fix this bug\" → NOT flagged (\"this\" is a determiner for \"bug\")\n3. **Vague referents:** other, something, someone, somewhere, anything, everything, stuff\n4. **Bare imperatives:** verb alone (\"Fix\") or verb + adjective with no object (\"Make good\", \"Clean up\", \"Make better/faster\")\n\n## Install\n\n1. Symlink or copy this directory to `~/.claude/skills/pronoun-resolver`\n2. Add the hook to `~/.claude/settings.json`:\n```json\n\"UserPromptSubmit\": [\n  {\n    \"hooks\": [\n      {\n        \"type\": \"command\",\n        \"command\": \"bash /ABSOLUTE/PATH/TO/.claude/skills/pronoun-resolver/bin/detect-pronouns.sh\"\n      }\n    ]\n  }\n]\n```\nNote: The path must be absolute. Update it if the skill is moved.\n\nFile v0.11.0:README.md\n\n# Pronoun Resolver\n\nA Claude Code hook that detects ambiguous references in user prompts and flags them for resolution. Zero-latency detection via regex/heuristics — Claude resolves using its own conversation context.\n\nNo LLM calls. No external API keys. Fires on every message, produces output only when ambiguity is detected.\n\n## The Problem\n\nWhen you type \"fix it\", Claude has to guess what \"it\" refers to. Sometimes it guesses right. Sometimes it confidently refactors the wrong file.\n\nWhen you type \"Make good\" with no context, Claude may invent an interpretation rather than asking.\n\nThis hook makes the ambiguity visible so Claude asks instead of guessing.\n\n## How It Works\n\n```\nUser types: \"fix it\"\n                |\n    +-----------v-----------+\n    |  Hook: detect-pronouns |\n    |  (regex + heuristic)   |\n    |  ~0ms, no LLM calls    |\n    +-----------+-----------+\n                | ambiguity detected\n    +-----------v-----------+\n    |  Output: flags +       |\n    |  compact preamble      |\n    +-----------+-----------+\n                |\n    +-----------v-----------+\n    |  Claude receives:      |\n    |  [PRONOUN-RESOLVER: Resolve using context. HIGH=act. LOW=ask.]  |\n    |  [AMBIGUOUS: pronouns=\"it\" | type=pronoun]                      |\n    |  fix it                |\n    +--------------------+---+\n                |\n    +-----------v-----------+\n    |  Claude resolves using |\n    |  conversation context  |\n    |  (GREEN/YELLOW/RED)    |\n    +------------------------+\n```\n\nClaude is the resolver. It has the conversation context. The hook just makes ambiguity explicit.\n\n## Detection Categories\n\n### 1. Personal Pronouns (always flagged)\n\n`it`, `them`, `they`, `its`\n\nThese are always referential — they can't be determiners.\n\n### 2. Demonstratives (smart filtering)\n\n`this`, `that`, `these`, `those`\n\nOnly flagged when used as standalone pronouns, NOT as determiners:\n\n| Prompt | Flagged? | Why |\n|--------|----------|-----|\n| `fix this` | Yes | \"this\" is standalone, no object |\n| `fix this bug` | No | \"this\" is a determiner for \"bug\" |\n| `do that and deploy` | Yes | \"that\" followed by conjunction |\n| `update that file` | No | \"that\" is a determiner for \"file\" |\n| `these tests are failing` | No | \"these\" is a determiner for \"tests\" |\n\n### 3. Vague Referents\n\n`other`, `something`, `someone`, `somewhere`, `anything`, `everything`, `stuff`\n\n### 4. Bare Imperatives (implicit subject)\n\nDetected when no pronouns or vague words are found. Catches commands with no explicit object:\n\n| Prompt | Detected | Subtype |\n|--------|----------|---------|\n| `Fix` | Yes | bare_verb |\n| `Make good` | Yes | verb_adjective |\n| `Make better/faster` | Yes | verb_adjective |\n| `Clean up` | Yes | verb_adjective |\n| `Fix the bug` | No | has explicit object |\n| `Add tests` | No | has noun object |\n\n## Resolution Tiering\n\nWhen Claude sees flags, it applies this framework:\n\n| Tier | Confidence | Action |\n|------|-----------|--------|\n| GREEN | 90%+ | Resolve silently, just act |\n| YELLOW | 70-90% | State assumption in one line, then act |\n| RED | <70% | Ask the user before acting |\n| BLACK | No context | Always ask (first message bare imperative) |\n\n## Self-Learning Ledger\n\nResolution accuracy is tracked at `~/.claude/skills/pronoun-resolver/.claude/pronoun-ledger.json` (inside the skill directory, never in your project). When Claude resolves a reference, it logs metadata — no raw prompt text is stored. When the user corrects it, the entry is marked and confidence calibration adjusts.\n\n```json\n{\n  \"resolutions\": [],\n  \"resolution_count\": 0,\n  \"adaptive_threshold\": 0.8,\n  \"context_reliability\": {}\n}\n```\n\n### How logging actually fires\n\nThe hook injects a `[PRONOUN-RESOLVER-LOG: ...]` directive on **every** flagged\nmessage, carrying the exact `bin/log-resolution.py` command and ledger path. The\nhook only *prints* this directive — Claude runs the command to record a\nresolution. The point is that the instruction is now present on every fire even\nwhen `SKILL.md` isn't loaded into context; previously the \"log it\" instruction\nlived only in the skill body, so it was almost never in context and the ledger\nalmost never updated. Claude logs only when it actually resolved a reference (not\nwhen it asked the user, or when a regex flag had no real referent).\n\n`bin/log-resolution.py` owns all writes so logging is safe by construction:\n\n- **Locked, atomic writes.** The whole read-modify-write runs under an exclusive\n  `flock`, so concurrent hook fires (e.g. parallel agents) never drop each\n  other's entries; the file is replaced atomically and never left half-written.\n- **Secret/PII redaction.** Every free-text field (`resolved_to`, the pronoun\n  token, context signal) is scanned before it touches disk. Known credential\n  shapes (API keys, tokens, JWTs, PEM keys, DB-URL creds, emails, SSNs, phone\n  numbers, long hex/base64 blobs) are replaced with `[redacted: possible\n  secret/PII]`; control characters (except tab/newline) are stripped and\n  over-long values truncated.\n- **Validated fields.** `prompt_hash` must be a hex digest or it's dropped (so\n  raw prompt text can't be smuggled in); `confidence` is clamped to `[0,1]` with\n  non-finite values falling back to `0.5`, and the writer refuses to emit\n  `NaN`/`Infinity` to the file (`allow_nan=False`).\n- **Corruption-safe.** A non-empty ledger that can't be parsed (or isn't the\n  expected object shape) is moved aside to `*.corrupt` rather than silently\n  overwritten.\n\nThe redactor is pattern-based defense-in-depth, not a guarantee: a novel\nsecret format or plain-English PII (a name, a street address) can still slip\nthrough. Prompts themselves are only ever hashed, never stored.\n\n## Data Retention\n\nThis skill stores two local files inside the skill directory (`~/.claude/skills/pronoun-resolver/.claude/`):\n\n- **pronoun-ledger.json** — resolution metadata (pronoun, resolved referent, confidence tier, correction status). Prompts are hashed, never stored as text.\n- **pronoun-resolver-analytics.jsonl** — per-message stats (timestamp, flag count, word count). No message content is stored.\n\nNo data is sent externally. Both files are local-only and can be deleted at any time without affecting functionality. To clear all stored data: `rm ~/.claude/skills/pronoun-resolver/.claude/pronoun-ledger.json ~/.claude/skills/pronoun-resolver/.claude/pronoun-resolver-analytics.jsonl`\n\n## File Structure\n\n```\npronoun-resolver/\n  SKILL.md                  # Skill definition + resolution framework\n  README.md                 # This file\n  bin/\n    detect-pronouns.sh      # Hook entry point — regex + orchestration\n    detect-implicit.py      # Bare imperative heuristic detector\n    log-resolution.py       # Locked, sanitizing ledger writer (the learning loop)\n    stats.py                # Analytics summary display\n  .claude/\n    pronoun-ledger.json     # Resolution metadata (auto-created)\n    pronoun-resolver-analytics.jsonl  # Per-message stats (auto-created)\n  tests/\n    test_log_resolution.py  # Unit tests for the ledger writer + sanitizer\n  evals/\n    cases.json              # Eval test cases\n    results.json            # Eval results\n```\n\n## Tests\n\n```bash\npython3 tests/test_log_resolution.py   # ledger writer, sanitizer, concurrency (no deps)\n```\n\nThe `evals/` suite exercises resolution *behavior* via the `claude` CLI and is\nseparate from these deterministic unit tests.\n\n## Install\n\n### 1. Clone/symlink the skill\n\n```bash\ngit clone https://github.com/kaicianflone/coding-pronoun-prompt-resolver.git\nln -s \"$(pwd)/coding-pronoun-prompt-resolver\" ~/.claude/skills/pronoun-resolver\n```\n\n### 2. Add the hook to `~/.claude/settings.json`\n\n```json\n{\n  \"hooks\": {\n    \"UserPromptSubmit\": [\n      {\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"bash /ABSOLUTE/PATH/TO/.claude/skills/pronoun-resolver/bin/detect-pronouns.sh\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\nReplace the path with your actual absolute path. The hook requires an absolute path.\n\n## Configuration\n\n### Disable for a project\n\n```bash\nmkdir -p .claude && touch .claude/pronoun-resolver-disabled\n```\n\n### Re-enable\n\n```bash\nrm .claude/pronoun-resolver-disabled\n```\n\n### Reset the ledger\n\n```bash\nrm ~/.claude/skills/pronoun-resolver/.claude/pronoun-ledger.json\n```\n\n## Requirements\n\n- Python 3.6+ (for bare imperative detection)\n- Bash 4+ (for arrays)\n- Claude Code with hooks support\n\n## License\n\nMIT\n\nFile v0.11.0:_meta.json\n\n{\n  \"ownerId\": \"kn7aakh8bj9gfbh6ah7rtw6pf180g5qr\",\n  \"slug\": \"pronoun-resolver\",\n  \"version\": \"0.11.0\",\n  \"publishedAt\": 1780243762001\n}\n\nFile v0.11.0:CHANGELOG.md\n\n# Changelog\n\nAll notable changes to the Pronoun Resolver skill are documented here.\n\n## [0.11.0] - 2026-05-31\n\n### Added\n- **Always-present logging directive.** The hook now injects a\n  `[PRONOUN-RESOLVER-LOG: ...]` directive on every flagged message, carrying the\n  exact `bin/log-resolution.py` command and ledger path. The hook prints the\n  directive; Claude runs it to record a resolution. The directive is now in\n  context on every fire even when `SKILL.md` isn't loaded (previously the logging\n  instruction lived only in the skill body, so the ledger almost never updated).\n- **`bin/log-resolution.py`** — a locked, sanitizing ledger writer that owns all\n  ledger mutations.\n- **`tests/test_log_resolution.py`** — dependency-free unit tests for the\n  sanitizer, ledger I/O, validation, and concurrency.\n\n### Security\n- **Secret/PII redaction** on every free-text field before it touches disk:\n  API keys, tokens (OpenAI/Stripe/GitHub/GitLab/Slack/npm/Google), JWTs, PEM\n  private keys, credentials in DB URLs, Bearer/Basic auth, emails, SSNs, phone\n  numbers, and long hex/base64 blobs. Control characters (except tab/newline)\n  stripped; over-long values truncated.\n- **`prompt_hash` validated** as a hex digest (raw text is dropped), and the\n  emitted hook directive single-quotes install-derived paths so a checkout path\n  containing shell metacharacters can't become executable syntax.\n\n### Fixed\n- **Concurrency race:** ledger writes now run under an exclusive `flock` across\n  the full read-modify-write, so parallel hook fires no longer drop entries.\n- **Corruption safety:** a non-empty ledger that can't be parsed (or isn't the\n  expected object shape) is backed up to `*.corrupt` instead of being silently\n  overwritten; `confidence` is clamped to `[0,1]` (non-finite → `0.5`) and the\n  writer refuses to emit `NaN`/`Infinity` (`allow_nan=False`).\n\nFile v0.11.0:skill-card.md\n\n## Description:\n\nDetects ambiguous pronouns, vague referents, and bare imperatives in user messages and flags them for resolution using conversation context.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[kaicianflone](https://clawhub.ai/user/kaicianflone)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and coding-agent users use this skill to make ambiguous prompts visible before an agent guesses the wrong referent. It guides the agent to resolve high-confidence references from conversation context, state assumptions for moderate confidence, or ask before acting when context is weak.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The hook runs on every submitted prompt and scans prompt text locally.\n\nMitigation: Install only where this behavior is acceptable, and use the documented project disable sentinel when prompt scanning should be inactive.\n\nRisk: The skill keeps local analytics and a resolution ledger under the skill directory.\n\nMitigation: Review the stored fields and delete the ledger or analytics files when retained metadata is no longer wanted.\n\nRisk: Stored free-text resolution metadata may still contain novel secret formats or plain-language personal data despite pattern-based redaction.\n\nMitigation: Avoid logging sensitive referents, review retained metadata periodically, and clear the local files for sensitive projects.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/kaicianflone/skills/pronoun-resolver)\n- [Publisher profile](https://clawhub.ai/user/kaicianflone)\n- [README](artifact/README.md)\n- [Changelog](artifact/CHANGELOG.md)\n- [Evaluation results](artifact/evals/results.json)\n\n## Skill Output:\n\n**Output Type(s):** [Text, Markdown, Shell commands, Configuration, Guidance]\n\n**Output Format:** [Markdown guidance with inline shell commands and local hook output flags]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Runs locally as a user-prompt-submit hook; stores local analytics and resolution metadata when the agent records a resolution.]\n\n## Skill Version(s):\n\n0.11.0 (source: SKILL.md frontmatter and release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v0.11.0:evals/cases.json\n\n[\n  {\n    \"id\": \"high-context-single-file\",\n    \"description\": \"Single pronoun with strong single-file context\",\n    \"prompt\": \"fix it\",\n    \"pronouns\": [\"it\"],\n    \"context\": \"User previously said: 'the login form in src/auth/LoginForm.tsx has a bug where it doesn't validate email format'. Assistant edited src/auth/LoginForm.tsx and added email validation regex.\",\n    \"context_reliability\": {\"last_edited_file\": 0.85, \"conversation_topic\": 0.7},\n    \"expected\": {\n      \"pronoun\": \"it\",\n      \"should_resolve\": true,\n      \"expected_referent_contains\": [\"LoginForm\", \"email\", \"validation\"],\n      \"min_confidence\": 0.8,\n      \"expected_idiomatic\": false,\n      \"expected_tier\": \"self-check\"\n    }\n  },\n  {\n    \"id\": \"high-context-multi-file\",\n    \"description\": \"Pronoun with context spanning multiple files\",\n    \"prompt\": \"update them\",\n    \"pronouns\": [\"them\"],\n    \"context\": \"User asked to 'add created_at and updated_at timestamps to the User model and the Order model'. Assistant edited models/user.py and models/order.py adding timestamp fields.\",\n    \"context_reliability\": {\"last_edited_file\": 0.8, \"conversation_topic\": 0.75},\n    \"expected\": {\n      \"pronoun\": \"them\",\n      \"should_resolve\": true,\n      \"expected_referent_contains\": [\"timestamp\", \"User\", \"Order\"],\n      \"min_confidence\": 0.7,\n      \"expected_idiomatic\": false,\n      \"expected_tier\": \"self-check\"\n    }\n  },\n  {\n    \"id\": \"medium-context-ambiguous\",\n    \"description\": \"Pronoun with context that could refer to two things -- should resolve to api endpoint (last tool call signal)\",\n    \"prompt\": \"delete it\",\n    \"pronouns\": [\"it\"],\n    \"context\": \"User discussed both 'the deprecated API endpoint at /api/v1/users' and 'the stale cache in redis'. Assistant ran tests on both. Last tool call was a curl to /api/v1/users.\",\n    \"context_reliability\": {\"last_tool_call\": 0.6, \"conversation_topic\": 0.5},\n    \"expected\": {\n      \"pronoun\": \"it\",\n      \"should_resolve\": true,\n      \"expected_referent_contains\": [\"api\"],\n      \"min_confidence\": 0.5,\n      \"expected_idiomatic\": false,\n      \"expected_tier_flexible\": true\n    }\n  },\n  {\n    \"id\": \"low-context-bare-pronoun\",\n    \"description\": \"Pronoun with zero useful context -- LLM may mark idiomatic or low-confidence; either is acceptable\",\n    \"prompt\": \"fix it\",\n    \"pronouns\": [\"it\"],\n    \"context\": \"(No prior conversation context available. Resolve based on the message alone.)\",\n    \"context_reliability\": {},\n    \"expected\": {\n      \"pronoun\": \"it\",\n      \"should_resolve\": false,\n      \"expected_referent_contains\": [],\n      \"min_confidence\": 0.0,\n      \"expected_idiomatic_flexible\": true,\n      \"expected_tier_flexible\": true\n    }\n  },\n  {\n    \"id\": \"self-contained-high-context\",\n    \"description\": \"Self-contained prompt with strong matching context -- should resolve to the auth handler confidently\",\n    \"prompt\": \"fix it in the auth handler\",\n    \"pronouns\": [\"it\"],\n    \"context\": \"User said 'there is a null pointer exception in src/auth/handler.ts at line 42 when the session cookie is missing'. Assistant read src/auth/handler.ts.\",\n    \"context_reliability\": {\"last_edited_file\": 0.9, \"recent_symbol\": 0.8},\n    \"expected\": {\n      \"pronoun\": \"it\",\n      \"should_resolve\": true,\n      \"expected_referent_contains\": [\"auth\", \"handler\"],\n      \"min_confidence\": 0.8,\n      \"expected_idiomatic_flexible\": true,\n      \"expected_tier\": \"self-check\"\n    }\n  },\n  {\n    \"id\": \"chained-pronouns\",\n    \"description\": \"Multiple chained pronouns requiring left-to-right resolution\",\n    \"prompt\": \"take that and apply it to these\",\n    \"pronouns\": [\"that\", \"it\", \"these\"],\n    \"context\": \"User asked to 'extract the rate limiting logic from api/middleware.ts into a shared utility'. Assistant created lib/rate-limit.ts. Then user said 'we also need this in the websocket handler and the graphql resolver'.\",\n    \"context_reliability\": {\"last_edited_file\": 0.8, \"conversation_topic\": 0.85},\n    \"expected\": {\n      \"pronoun\": \"that\",\n      \"should_resolve\": true,\n      \"expected_referent_contains\": [\"rate limit\"],\n      \"min_confidence\": 0.7,\n      \"expected_idiomatic\": false,\n      \"expected_tier\": \"self-check\"\n    }\n  },\n  {\n    \"id\": \"idiomatic-erlang\",\n    \"description\": \"Idiomatic phrase that should not be resolved\",\n    \"prompt\": \"let it crash\",\n    \"pronouns\": [\"it\"],\n    \"context\": \"User is building an Erlang/Elixir supervision tree.\",\n    \"context_reliability\": {\"conversation_topic\": 0.8},\n    \"expected\": {\n      \"pronoun\": \"it\",\n      \"should_resolve\": false,\n      \"expected_referent_contains\": [],\n      \"min_confidence\": 0.9,\n      \"expected_idiomatic\": true,\n      \"expected_tier\": \"self-check\"\n    }\n  },\n  {\n    \"id\": \"structural-with-context\",\n    \"description\": \"Standalone affirmation -- may resolve to the proposal or be treated as idiomatic\",\n    \"prompt\": \"that's correct\",\n    \"pronouns\": [\"that\"],\n    \"context\": \"Assistant proposed refactoring the payment processing pipeline to use an event-driven architecture with a message queue.\",\n    \"context_reliability\": {\"conversation_topic\": 0.75},\n    \"expected\": {\n      \"pronoun\": \"that\",\n      \"should_resolve\": false,\n      \"expected_referent_contains\": [\"refactor\", \"payment\"],\n      \"min_confidence\": 0.7,\n      \"expected_idiomatic_flexible\": true,\n      \"expected_tier\": \"self-check\"\n    }\n  },\n  {\n    \"id\": \"high-context-recent-symbol\",\n    \"description\": \"Pronoun referring to a recently discussed code symbol\",\n    \"prompt\": \"rename it\",\n    \"pronouns\": [\"it\"],\n    \"context\": \"User said 'the function processUserData in utils/transform.ts has a misleading name since it now handles both user and order data'. Assistant read the function.\",\n    \"context_reliability\": {\"recent_symbol\": 0.9, \"last_edited_file\": 0.6},\n    \"expected\": {\n      \"pronoun\": \"it\",\n      \"should_resolve\": true,\n      \"expected_referent_contains\": [\"processUserData\", \"utils/transform\"],\n      \"min_confidence\": 0.85,\n      \"expected_idiomatic\": false,\n      \"expected_tier\": \"self-check\"\n    }\n  },\n  {\n    \"id\": \"structural-with-adjacent-instruction\",\n    \"description\": \"Structural pronoun followed by clear instruction -- should be idiomatic or resolve to the proposal\",\n    \"prompt\": \"that's correct, now refactor the parser\",\n    \"pronouns\": [\"that\"],\n    \"context\": \"Assistant proposed a new approach to error handling.\",\n    \"context_reliability\": {\"conversation_topic\": 0.7},\n    \"expected\": {\n      \"pronoun\": \"that\",\n      \"should_resolve\": false,\n      \"expected_referent_contains\": [\"error handling\"],\n      \"min_confidence\": 0.7,\n      \"expected_idiomatic_flexible\": true,\n      \"expected_tier\": \"self-check\"\n    }\n  }\n]\n\nFile v0.11.0:evals/results.json\n\n{\n  \"timestamp\": \"2026-05-24T07:08:32Z\",\n  \"total\": 10,\n  \"passed\": 10,\n  \"failed\": 0,\n  \"cases\": [\n    {\n      \"case\": \"high-context-single-file\",\n      \"pass\": true,\n      \"scores\": {\n        \"found\": true,\n        \"idiomatic_correct\": true,\n        \"confidence_met\": true,\n        \"referent_match\": true,\n        \"referent_partial\": 1.0,\n        \"tier_correct\": true\n      },\n      \"confidence\": 0.88,\n      \"referent\": \"the email validation bug in src/auth/LoginForm.tsx\",\n      \"elapsed_s\": 14.6\n    },\n    {\n      \"case\": \"high-context-multi-file\",\n      \"pass\": true,\n      \"scores\": {\n        \"found\": true,\n        \"idiomatic_correct\": true,\n        \"confidence_met\": true,\n        \"referent_match\": true,\n        \"referent_partial\": 0.6666666666666666,\n        \"tier_correct\": true\n      },\n      \"confidence\": 0.88,\n      \"referent\": \"the User model and the Order model\",\n      \"elapsed_s\": 10.5\n    },\n    {\n      \"case\": \"medium-context-ambiguous\",\n      \"pass\": true,\n      \"scores\": {\n        \"found\": true,\n        \"idiomatic_correct\": true,\n        \"confidence_met\": true,\n        \"referent_match\": true,\n        \"referent_partial\": 1.0,\n        \"tier_correct\": true\n      },\n      \"confidence\": 0.7,\n      \"referent\": \"the deprecated API endpoint at /api/v1/users\",\n      \"elapsed_s\": 7.5\n    },\n    {\n      \"case\": \"low-context-bare-pronoun\",\n      \"pass\": true,\n      \"scores\": {\n        \"found\": true,\n        \"idiomatic_correct\": true,\n        \"confidence_met\": true,\n        \"referent_match\": true,\n        \"referent_partial\": 1.0,\n        \"tier_correct\": true\n      },\n      \"confidence\": 0.12,\n      \"referent\": \"previous context or known issue - insufficient prior conversation context to determine specific referent\",\n      \"elapsed_s\": 15.8\n    },\n    {\n      \"case\": \"self-contained-high-context\",\n      \"pass\": true,\n      \"scores\": {\n        \"found\": true,\n        \"idiomatic_correct\": true,\n        \"confidence_met\": true,\n        \"referent_match\": true,\n        \"referent_partial\": 1.0,\n        \"tier_correct\": true\n      },\n      \"confidence\": 0.89,\n      \"referent\": \"the null pointer exception in src/auth/handler.ts at line 42 when the session cookie is missing\",\n      \"elapsed_s\": 11.3\n    },\n    {\n      \"case\": \"chained-pronouns\",\n      \"pass\": true,\n      \"scores\": {\n        \"found\": true,\n        \"idiomatic_correct\": true,\n        \"confidence_met\": true,\n        \"referent_match\": true,\n        \"referent_partial\": 1.0,\n        \"tier_correct\": true\n      },\n      \"confidence\": 0.9,\n      \"referent\": \"the rate-limiting logic extracted to lib/rate-limit.ts\",\n      \"elapsed_s\": 11.6\n    },\n    {\n      \"case\": \"idiomatic-erlang\",\n      \"pass\": true,\n      \"scores\": {\n        \"found\": true,\n        \"idiomatic_correct\": true,\n        \"confidence_met\": true,\n        \"referent_match\": true,\n        \"referent_partial\": 1.0,\n        \"tier_correct\": true\n      },\n      \"confidence\": 0.99,\n      \"referent\": \"N/A\",\n      \"elapsed_s\": 5.8\n    },\n    {\n      \"case\": \"structural-with-context\",\n      \"pass\": true,\n      \"scores\": {\n        \"found\": true,\n        \"idiomatic_correct\": true,\n        \"confidence_met\": true,\n        \"referent_match\": true,\n        \"referent_partial\": 1.0,\n        \"tier_correct\": true\n      },\n      \"confidence\": 0.87,\n      \"referent\": \"the proposed refactoring of the payment processing pipeline to use event-driven architecture with a message queue\",\n      \"elapsed_s\": 12.7\n    },\n    {\n      \"case\": \"high-context-recent-symbol\",\n      \"pass\": true,\n      \"scores\": {\n        \"found\": true,\n        \"idiomatic_correct\": true,\n        \"confidence_met\": true,\n        \"referent_match\": true,\n        \"referent_partial\": 1.0,\n        \"tier_correct\": true\n      },\n      \"confidence\": 0.95,\n      \"referent\": \"the function processUserData in utils/transform.ts\",\n      \"elapsed_s\": 8.4\n    },\n    {\n      \"case\": \"structural-with-adjacent-instruction\",\n      \"pass\": true,\n      \"scores\": {\n        \"found\": true,\n        \"idiomatic_correct\": true,\n        \"confidence_met\": true,\n        \"referent_match\": true,\n        \"referent_partial\": 1.0,\n        \"tier_correct\": true\n      },\n      \"confidence\": 0.99,\n      \"referent\": \"N/A\",\n      \"elapsed_s\": 6.1\n    }\n  ]\n}\n\nArchive v0.10.0: 10 files, 17278 bytes\n\nFiles: bin/detect-implicit.py (2607b), bin/detect-pronouns.sh (5253b), bin/stats.py (1801b), evals/cases.json (6651b), evals/results.json (4242b), evals/run_evals.py (11868b), README.md (5984b), skill-card.md (1682b), SKILL.md (5291b), _meta.json (136b)\n\nFile v0.10.0:SKILL.md\n\n---\nname: pronoun-resolver\nversion: 0.10.0\ndescription: |\n  Detects ambiguous pronouns, vague referents, and bare imperatives in user messages\n  and flags them for resolution using conversation context. Zero-latency detection via\n  hook; resolution happens inside the conversation where context lives. Self-learning\n  via correction ledger with adaptive confidence tiering.\ncapabilities:\n  - user-prompt-submit hook (fires on every message, regex-only, no LLM calls)\n  - file-write: ~/.claude/skills/pronoun-resolver/.claude/pronoun-ledger.json (resolution metadata, no raw prompts)\n  - file-write: ~/.claude/skills/pronoun-resolver/.claude/pronoun-resolver-analytics.jsonl (per-message stats)\ndata_retention: |\n  All data is local-only, never transmitted externally. Prompts are hashed (SHA-256),\n  never stored as text. Both data files can be deleted without affecting functionality.\nhooks:\n  user-prompt-submit:\n    - type: command\n      command: \"bash ${CLAUDE_SKILL_DIR}/bin/detect-pronouns.sh\"\n      statusMessage: \"Scanning for ambiguous references...\"\n---\n\n# Pronoun Resolver\n\n## Arguments\n\nIf invoked with `--stats`: run `python3 ~/.claude/skills/pronoun-resolver/bin/stats.py` and display the output. Do not proceed with the rest of this skill.\n\n---\n\nYou are operating with the pronoun resolver active. When the hook detects ambiguous\nreferences in a user message, you will see flags injected before the message.\n\n## Your Role\n\nYOU are the resolver. You have the conversation context. The hook just detects — you decide.\n\n## Resolution Tiering\n\nWhen you see `[AMBIGUOUS:]` flags, apply this framework:\n\n### GREEN — Resolve silently (90%+ confidence)\nThe referent is obvious from the last 1-3 messages. Just act. Don't mention the resolution.\n- \"Fix it\" when you just showed them a bug → fix the bug\n- \"Make that work\" after discussing a failing test → fix the test\n\n### YELLOW — State assumption, proceed (70-90% confidence)\nYou're fairly sure but there's ambiguity. State what you're assuming in one line, then act.\n- \"I'm taking 'the other one' to mean `auth.ts` since we discussed two files. Acting on that.\"\n\n### RED — Ask before acting (<70% confidence)\nMultiple plausible referents, or no recent context to resolve against. Ask concisely.\n- \"What should I make good — the UI layout we discussed or the API response format?\"\n\n### BLACK — Bare imperative, no context at all\nFirst message of a conversation with no object. Always ask.\n- \"Make good\" with no prior context → \"What would you like me to improve?\"\n\n## Flag Format\n\nThe hook outputs a preamble followed by flags:\n```\n[PRONOUN-RESOLVER: Resolve these using conversation context. HIGH confidence=act silently. MEDIUM=state assumption then act. LOW/no context=ask user first.]\n[AMBIGUOUS: pronouns=\"it,that\" | type=pronoun]\n[AMBIGUOUS: vague=\"other,something\" | type=vague_referent]\n[AMBIGUOUS: implicit verb=\"make\" | type=bare_imperative | subtype=verb_adjective]\n```\n\n## Ledger\n\nResolution accuracy is tracked at `~/.claude/skills/pronoun-resolver/.claude/pronoun-ledger.json`.\nWhen you resolve an ambiguous reference, log it. When the user corrects you\n(\"no not that\", \"I meant X\"), mark the previous resolution as corrected.\n\nThe ledger schema:\n```json\n{\n  \"resolutions\": [...],\n  \"resolution_count\": 0,\n  \"adaptive_threshold\": 0.8,\n  \"context_reliability\": {}\n}\n```\n\nEach resolution entry:\n```json\n{\n  \"timestamp\": \"ISO8601\",\n  \"pronoun\": \"it\",\n  \"prompt_hash\": \"sha256 hex of the full prompt (no raw text stored)\",\n  \"resolved_to\": \"the auth middleware\",\n  \"tier_used\": \"green|yellow|red|black\",\n  \"confidence\": 0.92,\n  \"was_corrected\": false\n}\n```\n\nNever store raw prompt text in the ledger. Use `prompt_hash` for deduplication only.\n\n## Correction Detection\n\nIf the user's next message corrects your resolution:\n1. Mark the previous ledger entry as `was_corrected: true`\n2. Adjust your confidence calibration — if you're frequently wrong at a given tier, escalate more\n\n## Adaptation\n\nEvery 10 resolutions, check your accuracy:\n- If >90% correct at green tier → you're well calibrated\n- If <75% correct → shift toward yellow/red (ask more often)\n- Track which context signals (last edited file, recent discussion topic, etc.) are most reliable\n\n## Disable\n\nIf the user creates `.claude/pronoun-resolver-disabled` in the project root, stop resolving.\n\n## What Gets Detected\n\n1. **Personal pronouns** (always flagged): it, them, they, its\n2. **Demonstratives** (flagged only when standalone, not as determiners): this, that, these, those\n   - \"fix this\" → flagged (\"this\" is standalone pronoun)\n   - \"fix this bug\" → NOT flagged (\"this\" is a determiner for \"bug\")\n3. **Vague referents:** other, something, someone, somewhere, anything, everything, stuff\n4. **Bare imperatives:** verb alone (\"Fix\") or verb + adjective with no object (\"Make good\", \"Clean up\", \"Make better/faster\")\n\n## Install\n\n1. Symlink or copy this directory to `~/.claude/skills/pronoun-resolver`\n2. Add the hook to `~/.claude/settings.json`:\n```json\n\"UserPromptSubmit\": [\n  {\n    \"hooks\": [\n      {\n        \"type\": \"command\",\n        \"command\": \"bash /ABSOLUTE/PATH/TO/.claude/skills/pronoun-resolver/bin/detect-pronouns.sh\"\n      }\n    ]\n  }\n]\n```\nNote: The path must be absolute. Update it if the skill is moved.\n\nFile v0.10.0:README.md\n\n# Pronoun Resolver\n\nA Claude Code hook that detects ambiguous references in user prompts and flags them for resolution. Zero-latency detection via regex/heuristics — Claude resolves using its own conversation context.\n\nNo LLM calls. No external API keys. Fires on every message, produces output only when ambiguity is detected.\n\n## The Problem\n\nWhen you type \"fix it\", Claude has to guess what \"it\" refers to. Sometimes it guesses right. Sometimes it confidently refactors the wrong file.\n\nWhen you type \"Make good\" with no context, Claude may invent an interpretation rather than asking.\n\nThis hook makes the ambiguity visible so Claude asks instead of guessing.\n\n## How It Works\n\n```\nUser types: \"fix it\"\n                |\n    +-----------v-----------+\n    |  Hook: detect-pronouns |\n    |  (regex + heuristic)   |\n    |  ~0ms, no LLM calls    |\n    +-----------+-----------+\n                | ambiguity detected\n    +-----------v-----------+\n    |  Output: flags +       |\n    |  compact preamble      |\n    +-----------+-----------+\n                |\n    +-----------v-----------+\n    |  Claude receives:      |\n    |  [PRONOUN-RESOLVER: Resolve using context. HIGH=act. LOW=ask.]  |\n    |  [AMBIGUOUS: pronouns=\"it\" | type=pronoun]                      |\n    |  fix it                |\n    +--------------------+---+\n                |\n    +-----------v-----------+\n    |  Claude resolves using |\n    |  conversation context  |\n    |  (GREEN/YELLOW/RED)    |\n    +------------------------+\n```\n\nClaude is the resolver. It has the conversation context. The hook just makes ambiguity explicit.\n\n## Detection Categories\n\n### 1. Personal Pronouns (always flagged)\n\n`it`, `them`, `they`, `its`\n\nThese are always referential — they can't be determiners.\n\n### 2. Demonstratives (smart filtering)\n\n`this`, `that`, `these`, `those`\n\nOnly flagged when used as standalone pronouns, NOT as determiners:\n\n| Prompt | Flagged? | Why |\n|--------|----------|-----|\n| `fix this` | Yes | \"this\" is standalone, no object |\n| `fix this bug` | No | \"this\" is a determiner for \"bug\" |\n| `do that and deploy` | Yes | \"that\" followed by conjunction |\n| `update that file` | No | \"that\" is a determiner for \"file\" |\n| `these tests are failing` | No | \"these\" is a determiner for \"tests\" |\n\n### 3. Vague Referents\n\n`other`, `something`, `someone`, `somewhere`, `anything`, `everything`, `stuff`\n\n### 4. Bare Imperatives (implicit subject)\n\nDetected when no pronouns or vague words are found. Catches commands with no explicit object:\n\n| Prompt | Detected | Subtype |\n|--------|----------|---------|\n| `Fix` | Yes | bare_verb |\n| `Make good` | Yes | verb_adjective |\n| `Make better/faster` | Yes | verb_adjective |\n| `Clean up` | Yes | verb_adjective |\n| `Fix the bug` | No | has explicit object |\n| `Add tests` | No | has noun object |\n\n## Resolution Tiering\n\nWhen Claude sees flags, it applies this framework:\n\n| Tier | Confidence | Action |\n|------|-----------|--------|\n| GREEN | 90%+ | Resolve silently, just act |\n| YELLOW | 70-90% | State assumption in one line, then act |\n| RED | <70% | Ask the user before acting |\n| BLACK | No context | Always ask (first message bare imperative) |\n\n## Self-Learning Ledger\n\nResolution accuracy is tracked at `~/.claude/skills/pronoun-resolver/.claude/pronoun-ledger.json` (inside the skill directory, never in your project). When Claude resolves a reference, it logs metadata — no raw prompt text is stored. When the user corrects it, the entry is marked and confidence calibration adjusts.\n\n```json\n{\n  \"resolutions\": [],\n  \"resolution_count\": 0,\n  \"adaptive_threshold\": 0.8,\n  \"context_reliability\": {}\n}\n```\n\n## Data Retention\n\nThis skill stores two local files inside the skill directory (`~/.claude/skills/pronoun-resolver/.claude/`):\n\n- **pronoun-ledger.json** — resolution metadata (pronoun, resolved referent, confidence tier, correction status). Prompts are hashed, never stored as text.\n- **pronoun-resolver-analytics.jsonl** — per-message stats (timestamp, flag count, word count). No message content is stored.\n\nNo data is sent externally. Both files are local-only and can be deleted at any time without affecting functionality. To clear all stored data: `rm ~/.claude/skills/pronoun-resolver/.claude/pronoun-ledger.json ~/.claude/skills/pronoun-resolver/.claude/pronoun-resolver-analytics.jsonl`\n\n## File Structure\n\n```\npronoun-resolver/\n  SKILL.md                  # Skill definition + resolution framework\n  README.md                 # This file\n  bin/\n    detect-pronouns.sh      # Hook entry point — regex + orchestration\n    detect-implicit.py      # Bare imperative heuristic detector\n    stats.py                # Analytics summary display\n  .claude/\n    pronoun-ledger.json     # Resolution metadata (auto-created)\n    pronoun-resolver-analytics.jsonl  # Per-message stats (auto-created)\n  evals/\n    cases.json              # Eval test cases\n    results.json            # Eval results\n```\n\n## Install\n\n### 1. Clone/symlink the skill\n\n```bash\ngit clone https://github.com/kaicianflone/coding-pronoun-prompt-resolver.git\nln -s \"$(pwd)/coding-pronoun-prompt-resolver\" ~/.claude/skills/pronoun-resolver\n```\n\n### 2. Add the hook to `~/.claude/settings.json`\n\n```json\n{\n  \"hooks\": {\n    \"UserPromptSubmit\": [\n      {\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"bash /ABSOLUTE/PATH/TO/.claude/skills/pronoun-resolver/bin/detect-pronouns.sh\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\nReplace the path with your actual absolute path. The hook requires an absolute path.\n\n## Configuration\n\n### Disable for a project\n\n```bash\nmkdir -p .claude && touch .claude/pronoun-resolver-disabled\n```\n\n### Re-enable\n\n```bash\nrm .claude/pronoun-resolver-disabled\n```\n\n### Reset the ledger\n\n```bash\nrm ~/.claude/skills/pronoun-resolver/.claude/pronoun-ledger.json\n```\n\n## Requirements\n\n- Python 3.6+ (for bare imperative detection)\n- Bash 4+ (for arrays)\n- Claude Code with hooks support\n\n## License\n\nMIT\n\nFile v0.10.0:_meta.json\n\n{\n  \"ownerId\": \"kn7aakh8bj9gfbh6ah7rtw6pf180g5qr\",\n  \"slug\": \"pronoun-resolver\",\n  \"version\": \"0.10.0\",\n  \"publishedAt\": 1779763161768\n}\n\nFile v0.10.0:skill-card.md\n\n## Description: <br>\nDetects ambiguous pronouns, vague referents, and bare imperatives in user messages and flags them for resolution using conversation context. <br>\n\nThis skill is ready for commercial/non-commercial use. <br>\n\n## Publisher: <br>\n[kaicianflone](https://clawhub.ai/user/kaicianflone) <br>\n\n### License/Terms of Use: <br>\nMIT-0 <br>\n\n\n## Use Case: <br>\nDevelopers using Claude Code use this skill to surface ambiguous references in prompts so the agent can resolve clear referents from conversation context or ask for clarification before acting. <br>\n\n### Deployment Geography for Use: <br>\nGlobal <br>\n\n## Known Risks and Mitigations: <br>\nRisk: Review before execution as proposals could introduce incorrect or misleading guidance into skills. <br>\nMitigation: Review and scan skill before deployment. <br>\n\n## Reference(s): <br>\n- [ClawHub Skill Page](https://clawhub.ai/kaicianflone/pronoun-resolver) <br>\n\n\n## Skill Output: <br>\n**Output Type(s):** [text, shell commands, configuration, guidance] <br>\n**Output Format:** [Plain-text hook flags and Markdown setup guidance] <br>\n**Output Parameters:** [1D] <br>\n**Other Properties Related to Output:** [Runs as a local prompt hook, stores derived local metadata, and should require explicit confirmation for high-impact ambiguous requests.] <br>\n\n## Skill Version(s): <br>\n0.10.0 (source: frontmatter and server release evidence) <br>\n\n## Ethical Considerations: <br>\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment. <br>\n\nFile v0.10.0:evals/cases.json\n\n[\n  {\n    \"id\": \"high-context-single-file\",\n    \"description\": \"Single pronoun with strong single-file context\",\n    \"prompt\": \"fix it\",\n    \"pronouns\": [\"it\"],\n    \"context\": \"User previously said: 'the login form in src/auth/LoginForm.tsx has a bug where it doesn't validate email format'. Assistant edited src/auth/LoginForm.tsx and added email validation regex.\",\n    \"context_reliability\": {\"last_edited_file\": 0.85, \"conversation_topic\": 0.7},\n    \"expected\": {\n      \"pronoun\": \"it\",\n      \"should_resolve\": true,\n      \"expected_referent_contains\": [\"LoginForm\", \"email\", \"validation\"],\n      \"min_confidence\": 0.8,\n      \"expected_idiomatic\": false,\n      \"expected_tier\": \"self-check\"\n    }\n  },\n  {\n    \"id\": \"high-context-multi-file\",\n    \"description\": \"Pronoun with context spanning multiple files\",\n    \"prompt\": \"update them\",\n    \"pronouns\": [\"them\"],\n    \"context\": \"User asked to 'add created_at and updated_at timestamps to the User model and the Order model'. Assistant edited models/user.py and models/order.py adding timestamp fields.\",\n    \"context_reliability\": {\"last_edited_file\": 0.8, \"conversation_topic\": 0.75},\n    \"expected\": {\n      \"pronoun\": \"them\",\n      \"should_resolve\": true,\n      \"expected_referent_contains\": [\"timestamp\", \"User\", \"Order\"],\n      \"min_confidence\": 0.7,\n      \"expected_idiomatic\": false,\n      \"expected_tier\": \"self-check\"\n    }\n  },\n  {\n    \"id\": \"medium-context-ambiguous\",\n    \"description\": \"Pronoun with context that could refer to two things -- should resolve to api endpoint (last tool call signal)\",\n    \"prompt\": \"delete it\",\n    \"pronouns\": [\"it\"],\n    \"context\": \"User discussed both 'the deprecated API endpoint at /api/v1/users' and 'the stale cache in redis'. Assistant ran tests on both. Last tool call was a curl to /api/v1/users.\",\n    \"context_reliability\": {\"last_tool_call\": 0.6, \"conversation_topic\": 0.5},\n    \"expected\": {\n      \"pronoun\": \"it\",\n      \"should_resolve\": true,\n      \"expected_referent_contains\": [\"api\"],\n      \"min_confidence\": 0.5,\n      \"expected_idiomatic\": false,\n      \"expected_tier_flexible\": true\n    }\n  },\n  {\n    \"id\": \"low-context-bare-pronoun\",\n    \"description\": \"Pronoun with zero useful context -- LLM may mark idiomatic or low-confidence; either is acceptable\",\n    \"prompt\": \"fix it\",\n    \"pronouns\": [\"it\"],\n    \"context\": \"(No prior conversation context available. Resolve based on the message alone.)\",\n    \"context_reliability\": {},\n    \"expected\": {\n      \"pronoun\": \"it\",\n      \"should_resolve\": false,\n      \"expected_referent_contains\": [],\n      \"min_confidence\": 0.0,\n      \"expected_idiomatic_flexible\": true,\n      \"expected_tier_flexible\": true\n    }\n  },\n  {\n    \"id\": \"self-contained-high-context\",\n    \"description\": \"Self-contained prompt with strong matching context -- should resolve to the auth handler confidently\",\n    \"prompt\": \"fix it in the auth handler\",\n    \"pronouns\": [\"it\"],\n    \"context\": \"User said 'there is a null pointer exception in src/auth/handler.ts at line 42 when the session cookie is missing'. Assistant read src/auth/handler.ts.\",\n    \"context_reliability\": {\"last_edited_file\": 0.9, \"recent_symbol\": 0.8},\n    \"expected\": {\n      \"pronoun\": \"it\",\n      \"should_resolve\": true,\n      \"expected_referent_contains\": [\"auth\", \"handler\"],\n      \"min_confidence\": 0.8,\n      \"expected_idiomatic_flexible\": true,\n      \"expected_tier\": \"self-check\"\n    }\n  },\n  {\n    \"id\": \"chained-pronouns\",\n    \"description\": \"Multiple chained pronouns requiring left-to-right resolution\",\n    \"prompt\": \"take that and apply it to these\",\n    \"pronouns\": [\"that\", \"it\", \"these\"],\n    \"context\": \"User asked to 'extract the rate limiting logic from api/middleware.ts into a shared utility'. Assistant created lib/rate-limit.ts. Then user said 'we also need this in the websocket handler and the graphql resolver'.\",\n    \"context_reliability\": {\"last_edited_file\": 0.8, \"conversation_topic\": 0.85},\n    \"expected\": {\n      \"pronoun\": \"that\",\n      \"should_resolve\": true,\n      \"expected_referent_contains\": [\"rate limit\"],\n      \"min_confidence\": 0.7,\n      \"expected_idiomatic\": false,\n      \"expected_tier\": \"self-check\"\n    }\n  },\n  {\n    \"id\": \"idiomatic-erlang\",\n    \"description\": \"Idiomatic phrase that should not be resolved\",\n    \"prompt\": \"let it crash\",\n    \"pronouns\": [\"it\"],\n    \"context\": \"User is building an Erlang/Elixir supervision tree.\",\n    \"context_reliability\": {\"conversation_topic\": 0.8},\n    \"expected\": {\n      \"pronoun\": \"it\",\n      \"should_resolve\": false,\n      \"expected_referent_contains\": [],\n      \"min_confidence\": 0.9,\n      \"expected_idiomatic\": true,\n      \"expected_tier\": \"self-check\"\n    }\n  },\n  {\n    \"id\": \"structural-with-context\",\n    \"description\": \"Standalone affirmation -- may resolve to the proposal or be treated as idiomatic\",\n    \"prompt\": \"that's correct\",\n    \"pronouns\": [\"that\"],\n    \"context\": \"Assistant proposed refactoring the payment processing pipeline to use an event-driven architecture with a message queue.\",\n    \"context_reliability\": {\"conversation_topic\": 0.75},\n    \"expected\": {\n      \"pronoun\": \"that\",\n      \"should_resolve\": false,\n      \"expected_referent_contains\": [\"refactor\", \"payment\"],\n      \"min_confidence\": 0.7,\n      \"expected_idiomatic_flexible\": true,\n      \"expected_tier\": \"self-check\"\n    }\n  },\n  {\n    \"id\": \"high-context-recent-symbol\",\n    \"description\": \"Pronoun referring to a recently discussed code symbol\",\n    \"prompt\": \"rename it\",\n    \"pronouns\": [\"it\"],\n    \"context\": \"User said 'the function processUserData in utils/transform.ts has a misleading name since it now handles both user and order data'. Assistant read the function.\",\n    \"context_reliability\": {\"recent_symbol\": 0.9, \"last_edited_file\": 0.6},\n    \"expected\": {\n      \"pronoun\": \"it\",\n      \"should_resolve\": true,\n      \"expected_referent_contains\": [\"processUserData\", \"utils/transform\"],\n      \"min_confidence\": 0.85,\n      \"expected_idiomatic\": false,\n      \"expected_tier\": \"self-check\"\n    }\n  },\n  {\n    \"id\": \"structural-with-adjacent-instruction\",\n    \"description\": \"Structural pronoun followed by clear instruction -- should be idiomatic or resolve to the proposal\",\n    \"prompt\": \"that's correct, now refactor the parser\",\n    \"pronouns\": [\"that\"],\n    \"context\": \"Assistant proposed a new approach to error handling.\",\n    \"context_reliability\": {\"conversation_topic\": 0.7},\n    \"expected\": {\n      \"pronoun\": \"that\",\n      \"should_resolve\": false,\n      \"expected_referent_contains\": [\"error handling\"],\n      \"min_confidence\": 0.7,\n      \"expected_idiomatic_flexible\": true,\n      \"expected_tier\": \"self-check\"\n    }\n  }\n]\n\nFile v0.10.0:evals/results.json\n\n{\n  \"timestamp\": \"2026-05-24T07:08:32Z\",\n  \"total\": 10,\n  \"passed\": 10,\n  \"failed\": 0,\n  \"cases\": [\n    {\n      \"case\": \"high-context-single-file\",\n      \"pass\": true,\n      \"scores\": {\n        \"found\": true,\n        \"idiomatic_correct\": true,\n        \"confidence_met\": true,\n        \"referent_match\": true,\n        \"referent_partial\": 1.0,\n        \"tier_correct\": true\n      },\n      \"confidence\": 0.88,\n      \"referent\": \"the email validation bug in src/auth/LoginForm.tsx\",\n      \"elapsed_s\": 14.6\n    },\n    {\n      \"case\": \"high-context-multi-file\",\n      \"pass\": true,\n      \"scores\": {\n        \"found\": true,\n        \"idiomatic_correct\": true,\n        \"confidence_met\": true,\n        \"referent_match\": true,\n        \"referent_partial\": 0.6666666666666666,\n        \"tier_correct\": true\n      },\n      \"confidence\": 0.88,\n      \"referent\": \"the User model and the Order model\",\n      \"elapsed_s\": 10.5\n    },\n    {\n      \"case\": \"medium-context-ambiguous\",\n      \"pass\": true,\n      \"scores\": {\n        \"found\": true,\n        \"idiomatic_correct\": true,\n        \"confidence_met\": true,\n        \"referent_match\": true,\n        \"referent_partial\": 1.0,\n        \"tier_correct\": true\n      },\n      \"confidence\": 0.7,\n      \"referent\": \"the deprecated API endpoint at /api/v1/users\",\n      \"elapsed_s\": 7.5\n    },\n    {\n      \"case\": \"low-context-bare-pronoun\",\n      \"pass\": true,\n      \"scores\": {\n        \"found\": true,\n        \"idiomatic_correct\": true,\n        \"confidence_met\": true,\n        \"referent_match\": true,\n        \"referent_partial\": 1.0,\n        \"tier_correct\": true\n      },\n      \"confidence\": 0.12,\n      \"referent\": \"previous context or known issue - insufficient prior conversation context to determine specific referent\",\n      \"elapsed_s\": 15.8\n    },\n    {\n      \"case\": \"self-contained-high-context\",\n      \"pass\": true,\n      \"scores\": {\n        \"found\": true,\n        \"idiomatic_correct\": true,\n        \"confidence_met\": true,\n        \"referent_match\": true,\n        \"referent_partial\": 1.0,\n        \"tier_correct\": true\n      },\n      \"confidence\": 0.89,\n      \"referent\": \"the null pointer exception in src/auth/handler.ts at line 42 when the session cookie is missing\",\n      \"elapsed_s\": 11.3\n    },\n    {\n      \"case\": \"chained-pronouns\",\n      \"pass\": true,\n      \"scores\": {\n        \"found\": true,\n        \"idiomatic_correct\": true,\n        \"confidence_met\": true,\n        \"referent_match\": true,\n        \"referent_partial\": 1.0,\n        \"tier_correct\": true\n      },\n      \"confidence\": 0.9,\n      \"referent\": \"the rate-limiting logic extracted to lib/rate-limit.ts\",\n      \"elapsed_s\": 11.6\n    },\n    {\n      \"case\": \"idiomatic-erlang\",\n      \"pass\": true,\n      \"scores\": {\n        \"found\": true,\n        \"idiomatic_correct\": true,\n        \"confidence_met\": true,\n        \"referent_match\": true,\n        \"referent_partial\": 1.0,\n        \"tier_correct\": true\n      },\n      \"confidence\": 0.99,\n      \"referent\": \"N/A\",\n      \"elapsed_s\": 5.8\n    },\n    {\n      \"case\": \"structural-with-context\",\n      \"pass\": true,\n      \"scores\": {\n        \"found\": true,\n        \"idiomatic_correct\": true,\n        \"confidence_met\": true,\n        \"referent_match\": true,\n        \"referent_partial\": 1.0,\n        \"tier_correct\": true\n      },\n      \"confidence\": 0.87,\n      \"referent\": \"the proposed refactoring of the payment processing pipeline to use event-driven architecture with a message queue\",\n      \"elapsed_s\": 12.7\n    },\n    {\n      \"case\": \"high-context-recent-symbol\",\n      \"pass\": true,\n      \"scores\": {\n        \"found\": true,\n        \"idiomatic_correct\": true,\n        \"confidence_met\": true,\n        \"referent_match\": true,\n        \"referent_partial\": 1.0,\n        \"tier_correct\": true\n      },\n      \"confidence\": 0.95,\n      \"referent\": \"the function processUserData in utils/transform.ts\",\n      \"elapsed_s\": 8.4\n    },\n    {\n      \"case\": \"structural-with-adjacent-instruction\",\n      \"pass\": true,\n      \"scores\": {\n        \"found\": true,\n        \"idiomatic_correct\": true,\n        \"confidence_met\": true,\n        \"referent_match\": true,\n        \"referent_partial\": 1.0,\n        \"tier_correct\": true\n      },\n      \"confidence\": 0.99,\n      \"referent\": \"N/A\",\n      \"elapsed_s\": 6.1\n    }\n  ]\n}\n\nArchive v0.9.1: 8 files, 14385 bytes\n\nFiles: bin/detect-implicit.py (2607b), bin/detect-pronouns.sh (4424b), evals/cases.json (6651b), evals/results.json (4242b), evals/run_evals.py (11868b), README.md (4787b), SKILL.md (4466b), _meta.json (135b)\n\nFile v0.9.1:SKILL.md\n\n---\nname: pronoun-resolver\nversion: 0.9.1\ndescription: |\n  Detects ambiguous pronouns, vague referents, and bare imperatives in user messages\n  and flags them for resolution using conversation context. Zero-latency detection via\n  hook; resolution happens inside the conversation where context lives. Self-learning\n  via correction ledger with adaptive confidence tiering.\nhooks:\n  user-prompt-submit:\n    - type: command\n      command: \"bash ${CLAUDE_SKILL_DIR}/bin/detect-pronouns.sh\"\n      statusMessage: \"Scanning for ambiguous references...\"\n---\n\n# Pronoun Resolver\n\nYou are operating with the pronoun resolver active. When the hook detects ambiguous\nreferences in a user message, you will see flags injected before the message.\n\n## Your Role\n\nYOU are the resolver. You have the conversation context. The hook just detects — you decide.\n\n## Resolution Tiering\n\nWhen you see `[AMBIGUOUS:]` flags, apply this framework:\n\n### GREEN — Resolve silently (90%+ confidence)\nThe referent is obvious from the last 1-3 messages. Just act. Don't mention the resolution.\n- \"Fix it\" when you just showed them a bug → fix the bug\n- \"Make that work\" after discussing a failing test → fix the test\n\n### YELLOW — State assumption, proceed (70-90% confidence)\nYou're fairly sure but there's ambiguity. State what you're assuming in one line, then act.\n- \"I'm taking 'the other one' to mean `auth.ts` since we discussed two files. Acting on that.\"\n\n### RED — Ask before acting (<70% confidence)\nMultiple plausible referents, or no recent context to resolve against. Ask concisely.\n- \"What should I make good — the UI layout we discussed or the API response format?\"\n\n### BLACK — Bare imperative, no context at all\nFirst message of a conversation with no object. Always ask.\n- \"Make good\" with no prior context → \"What would you like me to improve?\"\n\n## Flag Format\n\nThe hook outputs a preamble followed by flags:\n```\n[PRONOUN-RESOLVER: Resolve these using conversation context. HIGH confidence=act silently. MEDIUM=state assumption then act. LOW/no context=ask user first.]\n[AMBIGUOUS: pronouns=\"it,that\" | type=pronoun]\n[AMBIGUOUS: vague=\"other,something\" | type=vague_referent]\n[AMBIGUOUS: implicit verb=\"make\" | type=bare_imperative | subtype=verb_adjective]\n```\n\n## Ledger\n\nResolution accuracy is tracked at `.claude/pronoun-ledger.json` in the project.\nWhen you resolve an ambiguous reference, log it. When the user corrects you\n(\"no not that\", \"I meant X\"), mark the previous resolution as corrected.\n\nThe ledger schema:\n```json\n{\n  \"resolutions\": [...],\n  \"resolution_count\": 0,\n  \"adaptive_threshold\": 0.8,\n  \"context_reliability\": {}\n}\n```\n\nEach resolution entry:\n```json\n{\n  \"timestamp\": \"ISO8601\",\n  \"pronoun\": \"it\",\n  \"original_prompt\": \"first 200 chars\",\n  \"resolved_to\": \"the auth middleware\",\n  \"tier_used\": \"green|yellow|red|black\",\n  \"confidence\": 0.92,\n  \"was_corrected\": false\n}\n```\n\n## Correction Detection\n\nIf the user's next message corrects your resolution:\n1. Mark the previous ledger entry as `was_corrected: true`\n2. Adjust your confidence calibration — if you're frequently wrong at a given tier, escalate more\n\n## Adaptation\n\nEvery 10 resolutions, check your accuracy:\n- If >90% correct at green tier → you're well calibrated\n- If <75% correct → shift toward yellow/red (ask more often)\n- Track which context signals (last edited file, recent discussion topic, etc.) are most reliable\n\n## Disable\n\nIf the user creates `.claude/pronoun-resolver-disabled` in the project root, stop resolving.\n\n## What Gets Detected\n\n1. **Personal pronouns** (always flagged): it, them, they, its\n2. **Demonstratives** (flagged only when standalone, not as determiners): this, that, these, those\n   - \"fix this\" → flagged (\"this\" is standalone pronoun)\n   - \"fix this bug\" → NOT flagged (\"this\" is a determiner for \"bug\")\n3. **Vague referents:** other, something, someone, somewhere, anything, everything, stuff\n4. **Bare imperatives:** verb alone (\"Fix\") or verb + adjective with no object (\"Make good\", \"Clean up\", \"Make better/faster\")\n\n## Install\n\n1. Symlink or copy this directory to `~/.claude/skills/pronoun-resolver`\n2. Add the hook to `~/.claude/settings.json`:\n```json\n\"UserPromptSubmit\": [\n  {\n    \"hooks\": [\n      {\n        \"type\": \"command\",\n        \"command\": \"bash /ABSOLUTE/PATH/TO/.claude/skills/pronoun-resolver/bin/detect-pronouns.sh\"\n      }\n    ]\n  }\n]\n```\nNote: The path must be absolute. Update it if the skill is moved.\n\nFile v0.9.1:README.md\n\n# Pronoun Resolver\n\nA Claude Code hook that detects ambiguous references in user prompts and flags them for resolution. Zero-latency detection via regex/heuristics — Claude resolves using its own conversation context.\n\nNo LLM calls. No external API keys. Fires on every message, produces output only when ambiguity is detected.\n\n## The Problem\n\nWhen you type \"fix it\", Claude has to guess what \"it\" refers to. Sometimes it guesses right. Sometimes it confidently refactors the wrong file.\n\nWhen you type \"Make good\" with no context, Claude may invent an interpretation rather than asking.\n\nThis hook makes the ambiguity visible so Claude asks instead of guessing.\n\n## How It Works\n\n```\nUser types: \"fix it\"\n                |\n    +-----------v-----------+\n    |  Hook: detect-pronouns |\n    |  (regex + heuristic)   |\n    |  ~0ms, no LLM calls    |\n    +-----------+-----------+\n                | ambiguity detected\n    +-----------v-----------+\n    |  Output: flags +       |\n    |  compact preamble      |\n    +-----------+-----------+\n                |\n    +-----------v-----------+\n    |  Claude receives:      |\n    |  [PRONOUN-RESOLVER: Resolve using context. HIGH=act. LOW=ask.]  |\n    |  [AMBIGUOUS: pronouns=\"it\" | type=pronoun]                      |\n    |  fix it                |\n    +--------------------+---+\n                |\n    +-----------v-----------+\n    |  Claude resolves using |\n    |  conversation context  |\n    |  (GREEN/YELLOW/RED)    |\n    +------------------------+\n```\n\nClaude is the resolver. It has the conversation context. The hook just makes ambiguity explicit.\n\n## Detection Categories\n\n### 1. Personal Pronouns (always flagged)\n\n`it`, `them`, `they`, `its`\n\nThese are always referential — they can't be determiners.\n\n### 2. Demonstratives (smart filtering)\n\n`this`, `that`, `these`, `those`\n\nOnly flagged when used as standalone pronouns, NOT as determiners:\n\n| Prompt | Flagged? | Why |\n|--------|----------|-----|\n| `fix this` | Yes | \"this\" is standalone, no object |\n| `fix this bug` | No | \"this\" is a determiner for \"bug\" |\n| `do that and deploy` | Yes | \"that\" followed by conjunction |\n| `update that file` | No | \"that\" is a determiner for \"file\" |\n| `these tests are failing` | No | \"these\" is a determiner for \"tests\" |\n\n### 3. Vague Referents\n\n`other`, `something`, `someone`, `somewhere`, `anything`, `everything`, `stuff`\n\n### 4. Bare Imperatives (implicit subject)\n\nDetected when no pronouns or vague words are found. Catches commands with no explicit object:\n\n| Prompt | Detected | Subtype |\n|--------|----------|---------|\n| `Fix` | Yes | bare_verb |\n| `Make good` | Yes | verb_adjective |\n| `Make better/faster` | Yes | verb_adjective |\n| `Clean up` | Yes | verb_adjective |\n| `Fix the bug` | No | has explicit object |\n| `Add tests` | No | has noun object |\n\n## Resolution Tiering\n\nWhen Claude sees flags, it applies this framework:\n\n| Tier | Confidence | Action |\n|------|-----------|--------|\n| GREEN | 90%+ | Resolve silently, just act |\n| YELLOW | 70-90% | State assumption in one line, then act |\n| RED | <70% | Ask the user before acting |\n| BLACK | No context | Always ask (first message bare imperative) |\n\n## Self-Learning Ledger\n\nResolution accuracy is tracked at `.claude/pronoun-ledger.json`. When Claude resolves a reference, it logs the result. When the user corrects it, the entry is marked and confidence calibration adjusts.\n\n```json\n{\n  \"resolutions\": [],\n  \"resolution_count\": 0,\n  \"adaptive_threshold\": 0.8,\n  \"context_reliability\": {}\n}\n```\n\n## File Structure\n\n```\npronoun-resolver/\n  SKILL.md                  # Skill definition + resolution framework\n  bin/\n    detect-pronouns.sh      # Hook entry point — regex + orchestration\n    detect-implicit.py      # Bare imperative heuristic detector\n```\n\n## Install\n\n### 1. Clone/symlink the skill\n\n```bash\ngit clone https://github.com/kaicianflone/coding-pronoun-prompt-resolver.git\nln -s \"$(pwd)/coding-pronoun-prompt-resolver\" ~/.claude/skills/pronoun-resolver\n```\n\n### 2. Add the hook to `~/.claude/settings.json`\n\n```json\n{\n  \"hooks\": {\n    \"UserPromptSubmit\": [\n      {\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"bash /ABSOLUTE/PATH/TO/.claude/skills/pronoun-resolver/bin/detect-pronouns.sh\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\nReplace the path with your actual absolute path. The hook requires an absolute path.\n\n## Configuration\n\n### Disable for a project\n\n```bash\nmkdir -p .claude && touch .claude/pronoun-resolver-disabled\n```\n\n### Re-enable\n\n```bash\nrm .claude/pronoun-resolver-disabled\n```\n\n### Reset the ledger\n\n```bash\nrm .claude/pronoun-ledger.json\n```\n\n## Requirements\n\n- Python 3.6+ (for bare imperative detection)\n- Bash 4+ (for arrays)\n- Claude Code with hooks support\n\n## License\n\nMIT\n\nFile v0.9.1:_meta.json\n\n{\n  \"ownerId\": \"kn7aakh8bj9gfbh6ah7rtw6pf180g5qr\",\n  \"slug\": \"pronoun-resolver\",\n  \"version\": \"0.9.1\",\n  \"publishedAt\": 1779723710230\n}\n\nFile v0.9.1:evals/cases.json\n\n[\n  {\n    \"id\": \"high-context-single-file\",\n    \"description\": \"Single pronoun with strong single-file context\",\n    \"prompt\": \"fix it\",\n    \"pronouns\": [\"it\"],\n    \"context\": \"User previously said: 'the login form in src/auth/LoginForm.tsx has a bug where it doesn't validate email format'. Assistant edited src/auth/LoginForm.tsx and added email validation regex.\",\n    \"context_reliability\": {\"last_edited_file\": 0.85, \"conversation_topic\": 0.7},\n    \"expected\": {\n      \"pronoun\": \"it\",\n      \"should_resolve\": true,\n      \"expected_referent_contains\": [\"LoginForm\", \"email\", \"validation\"],\n      \"min_confidence\": 0.8,\n      \"expected_idiomatic\": false,\n      \"expected_tier\": \"self-check\"\n    }\n  },\n  {\n    \"id\": \"high-context-multi-file\",\n    \"description\": \"Pronoun with context spanning multiple files\",\n    \"prompt\": \"update them\",\n    \"pronouns\": [\"them\"],\n    \"context\": \"User asked to 'add created_at and updated_at timestamps to the User model and the Order model'. Assistant edited models/user.py and models/order.py adding timestamp fields.\",\n    \"context_reliability\": {\"last_edited_file\": 0.8, \"conversation_topic\": 0.75},\n    \"expected\": {\n      \"pronoun\": \"them\",\n      \"should_resolve\": true,\n      \"expected_referent_contains\": [\"timestamp\", \"User\", \"Order\"],\n      \"min_confidence\": 0.7,\n      \"expected_idiomatic\": false,\n      \"expected_tier\": \"self-check\"\n    }\n  },\n  {\n    \"id\": \"medium-context-ambiguous\",\n    \"description\": \"Pronoun with context that could refer to two things -- should resolve to api endpoint (last tool call signal)\",\n    \"prompt\": \"delete it\",\n    \"pronouns\": [\"it\"],\n    \"context\": \"User discussed both 'the deprecated API endpoint at /api/v1/users' and 'the stale cache in redis'. Assistant ran tests on both. Last tool call was a curl to /api/v1/users.\",\n    \"context_reliability\": {\"last_tool_call\": 0.6, \"conversation_topic\": 0.5},\n    \"expected\": {\n      \"pronoun\": \"it\",\n      \"should_resolve\": true,\n      \"expected_referent_contains\": [\"api\"],\n      \"min_confidence\": 0.5,\n      \"expected_idiomatic\": false,\n      \"expected_tier_flexible\": true\n    }\n  },\n  {\n    \"id\": \"low-context-bare-pronoun\",\n    \"description\": \"Pronoun with zero useful context -- LLM may mark idiomatic or low-confidence; either is acceptable\",\n    \"prompt\": \"fix it\",\n    \"pronouns\": [\"it\"],\n    \"context\": \"(No prior conversation context available. Resolve based on the message alone.)\",\n    \"context_reliability\": {},\n    \"expected\": {\n      \"pronoun\": \"it\",\n      \"should_resolve\": false,\n      \"expected_referent_contains\": [],\n      \"min_confidence\": 0.0,\n      \"expected_idiomatic_flexible\": true,\n      \"expected_tier_flexible\": true\n    }\n  },\n  {\n    \"id\": \"self-contained-high-context\",\n    \"description\": \"Self-contained prompt with strong matching context -- should resolve to the auth handler confidently\",\n    \"prompt\": \"fix it in the auth handler\",\n    \"pronouns\": [\"it\"],\n    \"context\": \"User said 'there is a null pointer exception in src/auth/handler.ts at line 42 when the session cookie is missing'. Assistant read src/auth/handler.ts.\",\n    \"context_reliability\": {\"last_edited_file\": 0.9, \"recent_symbol\": 0.8},\n    \"expected\": {\n      \"pronoun\": \"it\",\n      \"should_resolve\": true,\n      \"expected_referent_contains\": [\"auth\", \"handler\"],\n      \"min_confidence\": 0.8,\n      \"expected_idiomatic_flexible\": true,\n      \"expected_tier\": \"self-check\"\n    }\n  },\n  {\n    \"id\": \"chained-pronouns\",\n    \"description\": \"Multiple chained pronouns requiring left-to-right resolution\",\n    \"prompt\": \"take that and apply it to these\",\n    \"pronouns\": [\"that\", \"it\", \"these\"],\n    \"context\": \"User asked to 'extract the rate limiting logic from api/middleware.ts into a shared utility'. Assistant created lib/rate-limit.ts. Then user said 'we also need this in the websocket handler and the graphql resolver'.\",\n    \"context_reliability\": {\"last_edited_file\": 0.8, \"conversation_topic\": 0.85},\n    \"expected\": {\n      \"pronoun\": \"that\",\n      \"should_resolve\": true,\n      \"expected_referent_contains\": [\"rate limit\"],\n      \"min_confidence\": 0.7,\n      \"expected_idiomatic\": false,\n      \"expected_tier\": \"self-check\"\n    }\n  },\n  {\n    \"id\": \"idiomatic-erlang\",\n    \"description\": \"Idiomatic phrase that should not be resolved\",\n    \"prompt\": \"let it crash\",\n    \"pronouns\": [\"it\"],\n    \"context\": \"User is building an Erlang/Elixir supervision tree.\",\n    \"context_reliability\": {\"conversation_topic\": 0.8},\n    \"expected\": {\n      \"pronoun\": \"it\",\n      \"should_resolve\": false,\n      \"expected_referent_contains\": [],\n      \"min_confidence\": 0.9,\n      \"expected_idiomatic\": true,\n      \"expected_tier\": \"self-check\"\n    }\n  },\n  {\n    \"id\": \"structural-with-context\",\n    \"description\": \"Standalone affirmation -- may resolve to the proposal or be treated as idiomatic\",\n    \"prompt\": \"that's correct\",\n    \"pronouns\": [\"that\"],\n    \"context\": \"Assistant proposed refactoring the payment processing pipeline to use an event-driven architecture with a message queue.\",\n    \"context_reliability\": {\"conversation_topic\": 0.75},\n    \"expected\": {\n      \"pronoun\": \"that\",\n      \"should_resolve\": false,\n      \"expected_referent_contains\": [\"refactor\", \"payment\"],\n      \"min_confidence\": 0.7,\n      \"expected_idiomatic_flexible\": true,\n      \"expected_tier\": \"self-check\"\n    }\n  },\n  {\n    \"id\": \"high-context-recent-symbol\",\n    \"description\": \"Pronoun referring to a recently discussed code symbol\",\n    \"prompt\": \"rename it\",\n    \"pronouns\": [\"it\"],\n    \"context\": \"User said 'the function processUserData in utils/transform.ts has a misleading name since it now handles both user and order data'. Assistant read the function.\",\n    \"context_reliability\": {\"recent_symbol\": 0.9, \"last_edited_file\": 0.6},\n    \"expected\": {\n      \"pronoun\": \"it\",\n      \"should_resolve\": true,\n      \"expected_referent_contains\": [\"processUserData\", \"utils/transform\"],\n      \"min_confidence\": 0.85,\n      \"expected_idiomatic\": false,\n      \"expected_tier\": \"self-check\"\n    }\n  },\n  {\n    \"id\": \"structural-with-adjacent-instruction\",\n    \"description\": \"Structural pronoun followed by clear instruction -- should be idiomatic or resolve to the proposal\",\n    \"prompt\": \"that's correct, now refactor the parser\",\n    \"pronouns\": [\"that\"],\n    \"context\": \"Assistant proposed a new approach to error handling.\",\n    \"context_reliability\": {\"conversation_topic\": 0.7},\n    \"expected\": {\n      \"pronoun\": \"that\",\n      \"should_resolve\": false,\n      \"expected_referent_contains\": [\"error handling\"],\n      \"min_confidence\": 0.7,\n      \"expected_idiomatic_flexible\": true,\n      \"expected_tier\": \"self-check\"\n    }\n  }\n]\n\nFile v0.9.1:evals/results.json\n\n{\n  \"timestamp\": \"2026-05-24T07:08:32Z\",\n  \"total\": 10,\n  \"passed\": 10,\n  \"failed\": 0,\n  \"cases\": [\n    {\n      \"case\": \"high-context-single-file\",\n      \"pass\": true,\n      \"scores\": {\n        \"found\": true,\n        \"idiomatic_correct\": true,\n        \"confidence_met\": true,\n        \"referent_match\": true,\n        \"referent_partial\": 1.0,\n        \"tier_correct\": true\n      },\n      \"confidence\": 0.88,\n      \"referent\": \"the email validation bug in src/auth/LoginForm.tsx\",\n      \"elapsed_s\": 14.6\n    },\n    {\n      \"case\": \"high-context-multi-file\",\n      \"pass\": true,\n      \"scores\": {\n        \"found\": true,\n        \"idiomatic_correct\": true,\n        \"confidence_met\": true,\n        \"referent_match\": true,\n        \"referent_partial\": 0.6666666666666666,\n        \"tier_correct\": true\n      },\n      \"confidence\": 0.88,\n      \"referent\": \"the User model and the Order model\",\n      \"elapsed_s\": 10.5\n    },\n    {\n      \"case\": \"medium-context-ambiguous\",\n      \"pass\": true,\n      \"scores\": {\n        \"found\": true,\n        \"idiomatic_correct\": true,\n        \"confidence_met\": true,\n        \"referent_match\": true,\n        \"referent_partial\": 1.0,\n        \"tier_correct\": true\n      },\n      \"confidence\": 0.7,\n      \"referent\": \"the deprecated API endpoint at /api/v1/users\",\n      \"elapsed_s\": 7.5\n    },\n    {\n      \"case\": \"low-context-bare-pronoun\",\n      \"pass\": true,\n      \"scores\": {\n        \"found\": true,\n        \"idiomatic_correct\": true,\n        \"confidence_met\": true,\n        \"referent_match\": true,\n        \"referent_partial\": 1.0,\n        \"tier_correct\": true\n      },\n      \"confidence\": 0.12,\n      \"referent\": \"previous context or known issue - insufficient prior conversation context to determine specific referent\",\n      \"elapsed_s\": 15.8\n    },\n    {\n      \"case\": \"self-contained-high-context\",\n      \"pass\": true,\n      \"scores\": {\n        \"found\": true,\n        \"idiomatic_correct\": true,\n        \"confidence_met\": true,\n        \"referent_match\": true,\n        \"referent_partial\": 1.0,\n        \"tier_correct\": true\n      },\n      \"confidence\": 0.89,\n      \"referent\": \"the null pointer exception in src/auth/handler.ts at line 42 when the session cookie is missing\",\n      \"elapsed_s\": 11.3\n    },\n    {\n      \"case\": \"chained-pronouns\",\n      \"pass\": true,\n      \"scores\": {\n        \"found\": true,\n        \"idiomatic_correct\": true,\n        \"confidence_met\": true,\n        \"referent_match\": true,\n        \"referent_partial\": 1.0,\n        \"tier_correct\": true\n      },\n      \"confidence\": 0.9,\n      \"referent\": \"the rate-limiting logic extracted to lib/rate-limit.ts\",\n      \"elapsed_s\": 11.6\n    },\n    {\n      \"case\": \"idiomatic-erlang\",\n      \"pass\": true,\n      \"scores\": {\n        \"found\": true,\n        \"idiomatic_correct\": true,\n        \"confidence_met\": true,\n        \"referent_match\": true,\n        \"referent_partial\": 1.0,\n        \"tier_correct\": true\n      },\n      \"confidence\": 0.99,\n      \"referent\": \"N/A\",\n      \"elapsed_s\": 5.8\n    },\n    {\n      \"case\": \"structural-with-context\",\n      \"pass\": true,\n      \"scores\": {\n        \"found\": true,\n        \"idiomatic_correct\": true,\n        \"confidence_met\": true,\n        \"referent_match\": true,\n        \"referent_partial\": 1.0,\n        \"tier_correct\": true\n      },\n      \"confidence\": 0.87,\n      \"referent\": \"the proposed refactoring of the payment processing pipeline to use event-driven architecture with a message queue\",\n      \"elapsed_s\": 12.7\n    },\n    {\n      \"case\": \"high-context-recent-symbol\",\n      \"pass\": true,\n      \"scores\": {\n        \"found\": true,\n        \"idiomatic_correct\": true,\n        \"confidence_met\": true,\n        \"referent_match\": true,\n        \"referent_partial\": 1.0,\n        \"tier_correct\": true\n      },\n      \"confidence\": 0.95,\n      \"referent\": \"the function processUserData in utils/transform.ts\",\n      \"elapsed_s\": 8.4\n    },\n    {\n      \"case\": \"structural-with-adjacent-instruction\",\n      \"pass\": true,\n      \"scores\": {\n        \"found\": true,\n        \"idiomatic_correct\": true,\n        \"confidence_met\": true,\n        \"referent_match\": true,\n        \"referent_partial\": 1.0,\n        \"tier_correct\": true\n      },\n      \"confidence\": 0.99,\n      \"referent\": \"N/A\",\n      \"elapsed_s\": 6.1\n    }\n  ]\n}\n\nArchive v0.9.0: 13 files, 19123 bytes\n\nFiles: bin/detect-pronouns.sh (3790b), bin/ledger.sh (3720b), bin/resolve.py (8785b), bin/resolve.sh (172b), evals/cases.json (6651b), evals/results.json (4242b), evals/run_evals.py (11868b), prompts/correction-detector.md (931b), prompts/council-agent.md (709b), prompts/self-check.md (1353b), README.md (9024b), SKILL.md (1743b), _meta.json (135b)\n\nFile v0.9.0:SKILL.md\n\n---\nname: pronoun-resolver\nversion: 0.1.0\ndescription: |\n  Intercepts ambiguous pronouns (it, them, these, those, that, this, they, its) in user\n  prompts and resolves them to specific referents using a tiered LLM engine before Claude\n  acts. Reduces hallucinations from vague input. Uses a self-learning ledger that adapts\n  confidence thresholds per project. Always active when installed.\nhooks:\n  user-prompt-submit:\n    - type: command\n      command: \"bash ${CLAUDE_SKILL_DIR}/bin/detect-pronouns.sh\"\n      statusMessage: \"Scanning for ambiguous pronouns...\"\n---\n\n# Pronoun Resolver\n\nAutomatically detects ambiguous pronouns in your prompts and resolves them to specific\nreferents before Claude acts on them.\n\n## How It Works\n\n1. Every message is scanned for pronouns: it, them, these, those, that, this, they, its\n2. If the prompt is self-contained (pronoun + specific noun), it passes through untouched\n3. If a pronoun is ambiguous, a quick LLM self-check resolves it with a confidence score\n4. If confidence is low, 3 independent LLM agents vote on the resolution\n5. The resolved referent is injected as context — your original message is never modified\n\n## Ledger\n\nResolutions are logged to `.claude/pronoun-ledger.json` in the project directory.\nThe ledger tracks accuracy and adjusts the confidence threshold over time:\n- High accuracy: trusts self-check more (fewer council escalations)\n- Low accuracy: escalates to council more often\n\n## Disable\n\nCreate `.claude/pronoun-resolver-disabled` in the project root to disable.\nDelete the file to re-enable.\n\n## Install\n\nSymlink or copy this directory to `~/.claude/skills/pronoun-resolver`:\n\n```bash\nln -s /path/to/coding-pronoun-prompt-resolver ~/.claude/skills/pronoun-resolver\n```\n\nFile v0.9.0:README.md\n\n# Pronoun Resolver\n\nA Claude Code skill that intercepts ambiguous pronouns in user prompts and resolves them to specific referents before Claude acts on them. Reduces hallucinations caused by vague input like \"fix it\", \"update them\", or \"is it possible.\"\n\nWorks automatically via a `user-prompt-submit` hook. No manual invocation needed. Zero LLM cost on messages with no pronouns.\n\n## The Problem\n\nWhen you type \"fix it\", Claude has to guess what \"it\" refers to. Sometimes it guesses right. Sometimes it confidently refactors the wrong file. The ambiguity in your prompt becomes a hallucination in the output.\n\nThis skill eliminates that guesswork by resolving pronouns before Claude sees your message.\n\n## How It Works\n\n```\nUser types: \"fix it\"\n                |\n    +-----------v-----------+\n    |  Regex pronoun scan   |\n    |  (zero LLM cost if    |\n    |   no pronouns found)  |\n    +-----------+-----------+\n                | pronouns detected\n    +-----------v-----------+\n    |  Tier 1: Self-Check   |\n    |  Single haiku call    |\n    |  Returns confidence   |\n    +-----------+-----------+\n                | confidence < threshold?\n           yes  |           | no\n    +-----------v---+   +---v-----------+\n    |  Tier 2:      |   |  Substitute   |\n    |  Council      |   |  silently     |\n    |  3 haiku      |   +---------------+\n    |  agents vote  |\n    +-------+-------+\n            |\n       majority?\n      yes   |     no\n    +---v---+ +---v-----------+\n    | Sub.  | | Ask the user  |\n    +-------+ +---------------+\n            |\n    +-------v-----------+\n    |  Claude receives:  |\n    |  [Pronoun Resolution: \"it\" -> \"auth middleware in src/server.ts\"]  |\n    |  fix it            |\n    +--------------------+\n```\n\nThe original message is never modified. Claude receives a disambiguation preamble alongside your prompt.\n\n## Detection: What Gets Flagged\n\n**Target pronouns:** `it`, `them`, `these`, `those`, `that`, `this`, `they`, `its`\n\nThe skill doesn't blindly flag every pronoun. It checks whether the prompt is **self-contained** -- whether it has enough nouns and specifics to resolve its own pronouns.\n\n### Flagged (ambiguous -- needs resolution)\n\n| Prompt | Why |\n|--------|-----|\n| `fix it` | \"it\" has no referent in the message |\n| `is it possible` | standalone question, \"it\" refers to prior context |\n| `that's correct` | standalone affirmation, \"that\" references something |\n| `update them` | \"them\" could be anything |\n| `take that and apply it to these` | three chained pronouns, all ambiguous |\n\n### Not flagged (self-contained -- passes through)\n\n| Prompt | Why |\n|--------|-----|\n| `fix it in the auth handler` | \"it\" is qualified by \"in the auth handler\" |\n| `is it possible to add retry logic` | full context provided |\n| `that's correct, now refactor the parser` | \"that\" is structural, real instruction is clear |\n| `update these test files` | \"these\" immediately followed by \"test files\" |\n| `refactor the auth handler in server.ts` | no pronouns at all |\n\n### Edge cases\n\n**Multiple pronouns:** `\"Fix it and update them\"` -- each resolved independently. If only one falls below the confidence threshold, only that one escalates to the council. The confident one substitutes immediately.\n\n**Chained references:** `\"Take that and apply it to these\"` -- resolved left-to-right. \"that\" first, then \"it\" (which may now reference the resolved \"that\"), then \"these.\"\n\n**Idiomatic uses:** `\"Let it crash\"`, `\"this is fine\"` -- the self-check recognizes genuine idioms and skips them. The ledger tracks these patterns so false positive rates decrease over time.\n\n## Tiered Resolution Engine\n\n### Tier 1: Quick Self-Check\n\nA single haiku-tier LLM call. Fast, cheap. Gets your message plus recent context and returns a structured resolution with a confidence score (0.0-1.0).\n\n```json\n{\n  \"pronoun\": \"it\",\n  \"referent\": \"the auth middleware in src/server.ts\",\n  \"confidence\": 0.92,\n  \"context_signal_used\": \"last_edited_file\",\n  \"idiomatic\": false\n}\n```\n\nIf confidence >= the adaptive threshold (default 0.8), the resolution is accepted and injected silently.\n\n### Tier 2: Council Vote\n\nTriggered only when Tier 1 confidence is below threshold. Spawns 3 independent haiku subagents. Each resolves the pronoun independently -- they don't see each other's answers (prevents anchoring bias).\n\n- **2/3 agree:** majority wins, substitute silently\n- **All 3 disagree:** falls back to asking you directly via AskUserQuestion (the only time the skill breaks silence)\n\n### Why tiered?\n\nMost pronouns are easy. \"fix it\" after you just edited one file? Haiku resolves that at 0.95 confidence in under a second. The council only fires for genuinely ambiguous cases, saving tokens and latency.\n\n## Self-Learning Ledger\n\nEvery resolution is logged to `.claude/pronoun-ledger.json` in your project directory. The ledger tracks three things:\n\n### 1. Resolution History\n\n```json\n{\n  \"timestamp\": \"2026-05-24T14:30:00Z\",\n  \"pronoun\": \"it\",\n  \"original_prompt\": \"fix it\",\n  \"resolved_to\": \"the auth middleware in src/server.ts\",\n  \"tier_used\": \"self-check\",\n  \"confidence\": 0.92,\n  \"context_signal_used\": \"last_edited_file\",\n  \"was_corrected\": false\n}\n```\n\nIf you correct the resolution (e.g., \"no not that, I meant the database migration\"), `was_corrected` flips to `true` and the ledger learns from the mistake.\n\n### 2. Context Reliability Scores\n\nTracks which context signals produce accurate resolutions for your project:\n\n```json\n{\n  \"last_edited_file\": 0.85,\n  \"last_tool_call\": 0.72,\n  \"conversation_topic\": 0.45,\n  \"recent_symbol\": 0.63\n}\n```\n\nScores update via exponential moving average (alpha=0.2). The self-check prompt receives these scores and weights more reliable signals higher.\n\n### 3. Adaptive Threshold\n\nStarts at 0.8. Recalculates every 10 resolutions:\n\n| Self-check accuracy | Threshold change | Effect |\n|---------------------|------------------|--------|\n| > 90% | drops 0.05 (min 0.6) | Trusts self-check more, fewer council calls |\n| 75-90% | no change | Stays the course |\n| < 75% | rises 0.05 (max 0.95) | Escalates to council more often |\n\nA project where you always mean \"the last file I edited\" will quickly learn to resolve confidently without the council. A project with ambiguous naming conventions will stay conservative.\n\n### Correction Detection\n\nThe skill watches your follow-up messages for correction signals:\n\n- Explicit: \"no not that\", \"I meant X\", \"wrong file\"\n- Redirections: \"the other one\", \"I was talking about Y\"\n- Frustration: \"why are you looking at X\"\n\nWhen detected, the most recent resolution is marked as corrected and the context reliability score for the signal that was used gets downgraded.\n\n### Maintenance\n\nEntries older than 30 days are pruned automatically on session startup. The ledger stays small -- a few hundred entries max for an active project.\n\n## File Structure\n\n```\npronoun-resolver/\n  SKILL.md                       # Skill definition + hook wiring\n  bin/\n    detect-pronouns.sh           # Hook entry point -- regex scan + orchestration\n    resolve.sh                   # Tiered resolution engine\n    ledger.sh                    # Ledger read/write/prune/threshold utilities\n  prompts/\n    self-check.md                # Tier 1 prompt template\n    council-agent.md             # Tier 2 prompt template (per subagent)\n    correction-detector.md       # Post-resolution correction detection prompt\n```\n\n## Install\n\n### From ClaWHub (recommended)\n\n```bash\nclawhub install pronoun-resolver\n```\n\n### From GitHub\n\n```bash\ngit clone https://github.com/kaicianflone/coding-pronoun-prompt-resolver.git\nln -s \"$(pwd)/coding-pronoun-prompt-resolver\" ~/.claude/skills/pronoun-resolver\n```\n\n### Manual\n\nCopy the entire directory to `~/.claude/skills/pronoun-resolver`.\n\nThe skill activates immediately. The `user-prompt-submit` hook fires on every message automatically.\n\n## Configuration\n\n### Disable for a project\n\n```bash\nmkdir -p .claude\ntouch .claude/pronoun-resolver-disabled\n```\n\n### Re-enable\n\n```bash\nrm .claude/pronoun-resolver-disabled\n```\n\n### Reset the ledger\n\n```bash\nrm .claude/pronoun-ledger.json\n```\n\nThe ledger will be re-created on the next resolution with default settings (threshold 0.8, all context signals at 0.5).\n\n### Gitignore\n\nAdd to your project's `.gitignore`:\n\n```\n.claude/pronoun-ledger.json\n.claude/pronoun-resolver-disabled\n```\n\nThe ledger is per-developer, per-project. It should not be committed.\n\n## Requirements\n\n- Claude Code CLI v2.0+ (`claude` command in PATH)\n- Python 3.6+\n- Bash 4+\n\n## How It Differs From System Prompt Instructions\n\nYou could add \"don't use pronouns\" to your system prompt. But that:\n- Only works if Claude follows the instruction (it often doesn't for short prompts)\n- Doesn't resolve what the pronoun actually means\n- Doesn't learn from your patterns over time\n- Adds to every prompt's token cost whether or not pronouns are present\n\nThis skill intercepts at the input layer, resolves concretely, costs nothing when there are no pronouns, and gets better over time.\n\n## License\n\nMIT\n\nFile v0.9.0:_meta.json\n\n{\n  \"ownerId\": \"kn7aakh8bj9gfbh6ah7rtw6pf180g5qr\",\n  \"slug\": \"pronoun-resolver\",\n  \"version\": \"0.9.0\",\n  \"publishedAt\": 1779606558120\n}\n\nFile v0.9.0:prompts/correction-detector.md\n\nYou are checking whether a user's follow-up message indicates they are correcting a previous pronoun resolution.\n\n## Input\n\nPrevious resolution: \"{{PRONOUN}}\" was resolved to \"{{RESOLVED_TO}}\"\n\nUser's follow-up message: {{USER_MESSAGE}}\n\n## Instructions\n\nDoes this follow-up message indicate the user is correcting the resolution? Look for:\n- Explicit corrections: \"no not that\", \"I meant X\", \"wrong file\", \"not that one\"\n- Redirections: \"the other one\", \"I was talking about X\", \"no, the Y\"\n- Frustration with wrong target: \"why are you looking at X\", \"that's not what I said\"\n\nDo NOT flag as correction:\n- New instructions unrelated to the resolution\n- Agreement or continuation (\"yes\", \"good\", \"now do X\")\n- Questions about the resolved target\n\n## Output\n\nReturn ONLY valid JSON, no markdown fences:\n\nIf correction: {\"is_correction\": true, \"corrected_referent\": \"what the user actually meant\"}\n\nIf not: {\"is_correction\": false}\n\nFile v0.9.0:prompts/council-agent.md\n\nYou are one of three independent judges resolving an ambiguous pronoun. You must determine what the pronoun refers to based solely on the context provided. Do NOT hedge or give multiple options. Commit to your best answer.\n\n## Input\n\nUser message: {{USER_MESSAGE}}\n\nPronoun to resolve: {{PRONOUN}}\n\nRecent conversation context (last 3-5 messages):\n{{CONVERSATION_CONTEXT}}\n\n## Instructions\n\nDetermine the single most likely referent for \"{{PRONOUN}}\" in the user's message. Be specific: name the file, function, variable, concept, or entity.\n\n## Output\n\nReturn ONLY valid JSON, no markdown fences, no explanation:\n\n{\"pronoun\": \"{{PRONOUN}}\", \"referent\": \"the specific thing it refers to\", \"confidence\": 0.85}\n\nFile v0.9.0:prompts/self-check.md\n\nYou are a pronoun resolver. Your job is to determine what ambiguous pronouns refer to in a user's message, given recent conversation context.\n\n## Input\n\nUser message: {{USER_MESSAGE}}\n\nDetected pronouns: {{PRONOUNS}}\n\nRecent conversation context (last 3-5 messages):\n{{CONVERSATION_CONTEXT}}\n\nContext reliability scores (higher = more reliable signal):\n{{CONTEXT_RELIABILITY}}\n\n## Instructions\n\nFor each detected pronoun, determine:\n1. What it most likely refers to (the \"referent\")\n2. How confident you are (0.0 to 1.0)\n3. Whether it's idiomatic/structural (not referencing a specific code entity)\n\nWeight your resolution toward context signals with higher reliability scores.\n\nIf the prompt is self-contained (the pronoun is immediately qualified by a noun, e.g., \"fix this function\"), mark it as idiomatic with confidence 0.99.\n\nFor chained pronouns (e.g., \"take that and apply it to these\"), resolve left-to-right. Later pronouns may reference earlier resolved ones.\n\n## Output\n\nReturn ONLY valid JSON, no markdown fences, no explanation:\n\n{\"resolutions\": [{\"pronoun\": \"it\", \"referent\": \"the specific thing it refers to\", \"confidence\": 0.92, \"context_signal_used\": \"last_edited_file\", \"idiomatic\": false}]}\n\nIf idiomatic:\n\n{\"resolutions\": [{\"pronoun\": \"it\", \"referent\": \"N/A\", \"confidence\": 0.99, \"context_signal_used\": \"none\", \"idiomatic\": true}]}\n\nFile v0.9.0:evals/cases.json\n\n[\n  {\n    \"id\": \"high-context-single-file\",\n    \"description\": \"Single pronoun with strong single-file context\",\n    \"prompt\": \"fix it\",\n    \"pronouns\": [\"it\"],\n    \"context\": \"User previously said: 'the login form in src/auth/LoginForm.tsx has a bug where it doesn't validate email format'. Assistant edited src/auth/LoginForm.tsx and added email validation regex.\",\n    \"context_reliability\": {\"last_edited_file\": 0.85, \"conversation_topic\": 0.7},\n    \"expected\": {\n      \"pronoun\": \"it\",\n      \"should_resolve\": true,\n      \"expected_referent_contains\": [\"LoginForm\", \"email\", \"validation\"],\n      \"min_confidence\": 0.8,\n      \"expected_idiomatic\": false,\n      \"expected_tier\": \"self-check\"\n    }\n  },\n  {\n    \"id\": \"high-context-multi-file\",\n    \"description\": \"Pronoun with context spanning multiple files\",\n    \"prompt\": \"update them\",\n    \"pronouns\": [\"them\"],\n    \"context\": \"User asked to 'add created_at and updated_at timestamps to the User model and the Order model'. Assistant edited models/user.py and models/order.py adding timestamp fields.\",\n    \"context_reliability\": {\"last_edited_file\": 0.8, \"conversation_topic\": 0.75},\n    \"expected\": {\n      \"pronoun\": \"them\",\n      \"should_resolve\": true,\n      \"expected_referent_contains\": [\"timestamp\", \"User\", \"Order\"],\n      \"min_confidence\": 0.7,\n      \"expected_idiomatic\": false,\n      \"expected_tier\": \"self-check\"\n    }\n  },\n  {\n    \"id\": \"medium-context-ambiguous\",\n    \"description\": \"Pronoun with context that could refer to two things -- should resolve to api endpoint (last tool call signal)\",\n    \"prompt\": \"delete it\",\n    \"pronouns\": [\"it\"],\n    \"context\": \"User discussed both 'the deprecated API endpoint at /api/v1/users' and 'the stale cache in redis'. Assistant ran tests on both. Last tool call was a curl to /api/v1/users.\",\n    \"context_reliability\": {\"last_tool_call\": 0.6, \"conversation_topic\": 0.5},\n    \"expected\": {\n      \"pronoun\": \"it\",\n      \"should_resolve\": true,\n      \"expected_referent_contains\": [\"api\"],\n      \"min_confidence\": 0.5,\n      \"expected_idiomatic\": false,\n      \"expected_tier_flexible\": true\n    }\n  },\n  {\n    \"id\": \"low-context-bare-pronoun\",\n    \"description\": \"Pronoun with zero useful context -- LLM may mark idiomatic or low-confidence; either is acceptable\",\n    \"prompt\": \"fix it\",\n    \"pronouns\": [\"it\"],\n    \"context\": \"(No prior conversation context available. Resolve based on the message alone.)\",\n    \"context_reliability\": {},\n    \"expected\": {\n      \"pronoun\": \"it\",\n      \"should_resolve\": false,\n      \"expected_referent_contains\": [],\n      \"min_confidence\": 0.0,\n      \"expected_idiomatic_flexible\": true,\n      \"expected_tier_flexible\": true\n    }\n  },\n  {\n    \"id\": \"self-contained-high-context\",\n    \"description\": \"Self-contained prompt with strong matching context -- should resolve to the auth handler confidently\",\n    \"prompt\": \"fix it in the auth handler\",\n    \"pronouns\": [\"it\"],\n    \"context\": \"User said 'there is a null pointer exception in src/auth/handler.ts at line 42 when the session cookie is missing'. Assistant read src/auth/handler.ts.\",\n    \"context_reliability\": {\"last_edited_file\": 0.9, \"recent_symbol\": 0.8},\n    \"expected\": {\n      \"pronoun\": \"it\",\n      \"should_resolve\": true,\n      \"expected_referent_contains\": [\"auth\", \"handler\"],\n      \"min_confidence\": 0.8,\n      \"expected_idiomatic_flexible\": true,\n      \"expected_tier\": \"self-check\"\n    }\n  },\n  {\n    \"id\": \"chained-pronouns\",\n    \"description\": \"Multiple chained pronouns requiring left-to-right resolution\",\n    \"prompt\": \"take that and apply it to these\",\n    \"pronouns\": [\"that\", \"it\", \"these\"],\n    \"context\": \"User asked to 'extract the rate limiting logic from api/middleware.ts into a shared utility'. Assistant created lib/rate-limit.ts. Then user said 'we also need this in the websocket handler and the graphql resolver'.\",\n    \"context_reliability\": {\"last_edited_file\": 0.8, \"conversation_topic\": 0.85},\n    \"expected\": {\n      \"pronoun\": \"that\",\n      \"should_resolve\": true,\n      \"expected_referent_contains\": [\"rate limit\"],\n      \"min_confidence\": 0.7,\n      \"expected_idiomatic\": false,\n      \"expected_tier\": \"self-check\"\n    }\n  },\n  {\n    \"id\": \"idiomatic-erlang\",\n    \"description\": \"Idiomatic phrase that should not be resolved\",\n    \"prompt\": \"let it crash\",\n    \"pronouns\": [\"it\"],\n    \"context\": \"User is building an Erlang/Elixir supervision tree.\",\n    \"context_reliability\": {\"conversation_topic\": 0.8},\n    \"expected\": {\n      \"pronoun\": \"it\",\n      \"should_resolve\": false,\n      \"expected_referent_contains\": [],\n      \"min_confidence\": 0.9,\n      \"expected_idiomatic\": true,\n      \"expected_tier\": \"self-check\"\n    }\n  },\n  {\n    \"id\": \"structural-with-context\",\n    \"description\": \"Standalone affirmation -- may resolve to the proposal or be treated as idiomatic\",\n    \"prompt\": \"that's correct\",\n    \"pronouns\": [\"that\"],\n    \"context\": \"Assistant proposed refactoring the payment processing pipeline to use an event-driven architecture with a message queue.\",\n    \"context_reliability\": {\"conversation_topic\": 0.75},\n    \"expected\": {\n      \"pronoun\": \"that\",\n      \"should_resolve\": false,\n      \"expected_referent_contains\": [\"refactor\", \"payment\"],\n      \"min_confidence\": 0.7,\n      \"expected_idiomatic_flexible\": true,\n      \"expected_tier\": \"self-check\"\n    }\n  },\n  {\n    \"id\": \"high-context-recent-symbol\",\n    \"description\": \"Pronoun referring to a recently discussed code symbol\",\n    \"prompt\": \"rename it\",\n    \"pronouns\": [\"it\"],\n    \"context\": \"User said 'the function processUserData in utils/transform.ts has a misleading name since it now handles both user and order data'. Assistant read the function.\",\n    \"context_reliability\": {\"recent_symbol\": 0.9, \"last_edited_file\": 0.6},\n    \"expected\": {\n      \"pronoun\": \"it\",\n      \"should_resolve\": true,\n      \"expected_referent_contains\": [\"processUserData\", \"utils/transform\"],\n      \"min_confidence\": 0.85,\n      \"expected_idiomatic\": false,\n      \"expected_tier\": \"self-check\"\n    }\n  },\n  {\n    \"id\": \"structural-with-adjacent-instruction\",\n    \"description\": \"Structural pronoun followed by clear instruction -- should be idiomatic or resolve to the proposal\",\n    \"prompt\": \"that's correct, now refactor the parser\",\n    \"pronouns\": [\"that\"],\n    \"context\": \"Assistant proposed a new approach to error handling.\",\n    \"context_reliability\": {\"conversation_topic\": 0.7},\n    \"expected\": {\n      \"pronoun\": \"that\",\n      \"should_resolve\": false,\n      \"expected_referent_contains\": [\"error handling\"],\n      \"min_confidence\": 0.7,\n      \"expected_idiomatic_flexible\": true,\n      \"expected_tier\": \"self-check\"\n    }\n  }\n]\n\nFile v0.9.0:evals/results.json\n\n{\n  \"timestamp\": \"2026-05-24T07:08:32Z\",\n  \"total\": 10,\n  \"passed\": 10,\n  \"failed\": 0,\n  \"cases\": [\n    {\n      \"case\": \"high-context-single-file\",\n      \"pass\": true,\n      \"scores\": {\n        \"found\": true,\n        \"idiomatic_correct\": true,\n        \"confidence_met\": true,\n        \"referent_match\": true,\n        \"referent_partial\": 1.0,\n        \"tier_correct\": true\n      },\n      \"confidence\": 0.88,\n      \"referent\": \"the email validation bug in src/auth/LoginForm.tsx\",\n      \"elapsed_s\": 14.6\n    },\n    {\n      \"case\": \"high-context-multi-file\",\n      \"pass\": true,\n      \"scores\": {\n        \"found\": true,\n        \"idiomatic_correct\": true,\n        \"confidence_met\": true,\n        \"referent_match\": true,\n        \"referent_partial\": 0.6666666666666666,\n        \"tier_correct\": true\n      },\n      \"confidence\": 0.88,\n      \"referent\": \"the User model and the Order model\",\n      \"elapsed_s\": 10.5\n    },\n    {\n      \"case\": \"medium-context-ambiguous\",\n      \"pass\": true,\n      \"scores\": {\n        \"found\": true,\n        \"idiomatic_correct\": true,\n        \"confidence_met\": true,\n        \"referent_match\": true,\n        \"referent_partial\": 1.0,\n        \"tier_correct\": true\n      },\n      \"confidence\": 0.7,\n      \"referent\": \"the deprecated API endpoint at /api/v1/users\",\n      \"elapsed_s\": 7.5\n    },\n    {\n      \"case\": \"low-context-bare-pronoun\",\n      \"pass\": true,\n      \"scores\": {\n        \"found\": true,\n        \"idiomatic_correct\": true,\n        \"confidence_met\": true,\n        \"referent_match\": true,\n        \"referent_partial\": 1.0,\n        \"tier_correct\": true\n      },\n      \"confidence\": 0.12,\n      \"referent\": \"previous context or known issue - insufficient prior conversation context to determine specific referent\",\n      \"elapsed_s\": 15.8\n    },\n    {\n      \"case\": \"self-contained-high-context\",\n      \"pass\": true,\n      \"scores\": {\n        \"found\": true,\n        \"idiomatic_correct\": true,\n        \"confidence_met\": true,\n        \"referent_match\": true,\n        \"referent_partial\": 1.0,\n        \"tier_correct\": true\n      },\n      \"confidence\": 0.89,\n      \"referent\": \"the null pointer exception in src/auth/handler.ts at line 42 when the session cookie is missing\",\n      \"elapsed_s\": 11.3\n    },\n    {\n      \"case\": \"chained-pronouns\",\n      \"pass\": true,\n      \"scores\": {\n        \"found\": true,\n        \"idiomatic_correct\": true,\n        \"confidence_met\": true,\n        \"referent_match\": true,\n        \"referent_partial\": 1.0,\n        \"tier_correct\": true\n      },\n      \"confidence\": 0.9,\n      \"referent\": \"the rate-limiting logic extracted to lib/rate-limit.ts\",\n      \"elapsed_s\": 11.6\n    },\n    {\n      \"case\": \"idiomatic-erlang\",\n      \"pass\": true,\n      \"scores\": {\n        \"found\": true,\n        \"idiomatic_correct\": true,\n        \"confidence_met\": true,\n        \"referent_match\": true,\n        \"referent_partial\": 1.0,\n        \"tier_correct\": true\n      },\n      \"confidence\": 0.99,\n      \"referent\": \"N/A\",\n      \"elapsed_s\": 5.8\n    },\n    {\n      \"case\": \"structural-with-context\",\n      \"pass\": true,\n      \"scores\": {\n        \"found\": true,\n        \"idiomatic_correct\": true,\n        \"confidence_met\": true,\n        \"referent_match\": true,\n        \"referent_partial\": 1.0,\n        \"tier_correct\": true\n      },\n      \"confidence\": 0.87,\n      \"referent\": \"the proposed refactoring of the payment processing pipeline to use event-driven architecture with a message queue\",\n      \"elapsed_s\": 12.7\n    },\n    {\n      \"case\": \"high-context-recent-symbol\",\n      \"pass\": true,\n      \"scores\": {\n        \"found\": true,\n        \"idiomatic_correct\": true,\n        \"confidence_met\": true,\n        \"referent_match\": true,\n        \"referent_partial\": 1.0,\n        \"tier_correct\": true\n      },\n      \"confidence\": 0.95,\n      \"referent\": \"the function processUserData in utils/transform.ts\",\n      \"elapsed_s\": 8.4\n    },\n    {\n      \"case\": \"structural-with-adjacent-instruction\",\n      \"pass\": true,\n      \"scores\": {\n        \"found\": true,\n        \"idiomatic_correct\": true,\n        \"confidence_met\": true,\n        \"referent_match\": true,\n        \"referent_partial\": 1.0,\n        \"tier_correct\": true\n      },\n      \"confidence\": 0.99,\n      \"referent\": \"N/A\",\n      \"elapsed_s\": 6.1\n    }\n  ]\n}\n\nArchive v0.1.0: 9 files, 12624 bytes\n\nFiles: bin/detect-pronouns.sh (3539b), bin/ledger.sh (3720b), bin/resolve.sh (7724b), prompts/correction-detector.md (931b), prompts/council-agent.md (709b), prompts/self-check.md (1353b), README.md (9024b), SKILL.md (1743b), _meta.json (135b)\n\nFile v0.1.0:SKILL.md\n\n---\nname: pronoun-resolver\nversion: 0.1.0\ndescription: |\n  Intercepts ambiguous pronouns (it, them, these, those, that, this, they, its) in user\n  prompts and resolves them to specific referents using a tiered LLM engine before Claude\n  acts. Reduces hallucinations from vague input. Uses a self-learning ledger that adapts\n  confidence thresholds per project. Always active when installed.\nhooks:\n  user-prompt-submit:\n    - type: command\n      command: \"bash ${CLAUDE_SKILL_DIR}/bin/detect-pronouns.sh\"\n      statusMessage: \"Scanning for ambiguous pronouns...\"\n---\n\n# Pronoun Resolver\n\nAutomatically detects ambiguous pronouns in your prompts and resolves them to specific\nreferents before Claude acts on them.\n\n## How It Works\n\n1. Every message is scanned for pronouns: it, them, these, those, that, this, they, its\n2. If the prompt is self-contained (pronoun + specific noun), it passes through untouched\n3. If a pronoun is ambiguous, a quick LLM self-check resolves it with a confidence score\n4. If confidence is low, 3 independent LLM agents vote on the resolution\n5. The resolved referent is injected as context — your original message is never modified\n\n## Ledger\n\nResolutions are logged to `.claude/pronoun-ledger.json` in the project directory.\nThe ledger tracks accuracy and adjusts the confidence threshold over time:\n- High accuracy: trusts self-check more (fewer council escalations)\n- Low accuracy: escalates to council more often\n\n## Disable\n\nCreate `.claude/pronoun-resolver-disabled` in the project root to disable.\nDelete the file to re-enable.\n\n## Install\n\nSymlink or copy this directory to `~/.claude/skills/pronoun-resolver`:\n\n```bash\nln -s /path/to/coding-pronoun-prompt-resolver ~/.claude/skills/pronoun-resolver\n```\n\nFile v0.1.0:README.md\n\n# Pronoun Resolver\n\nA Claude Code skill that intercepts ambiguous pronouns in user prompts and resolves them to specific referents before Claude acts on them. Reduces hallucinations caused by vague input like \"fix it\", \"update them\", or \"is it possible.\"\n\nWorks automatically via a `user-prompt-submit` hook. No manual invocation needed. Zero LLM cost on messages with no pronouns.\n\n## The Problem\n\nWhen you type \"fix it\", Claude has to guess what \"it\" refers to. Sometimes it guesses right. Sometimes it confidently refactors the wrong file. The ambiguity in your prompt becomes a hallucination in the output.\n\nThis skill eliminates that guesswork by resolving pronouns before Claude sees your message.\n\n## How It Works\n\n```\nUser types: \"fix it\"\n                |\n    +-----------v-----------+\n    |  Regex pronoun scan   |\n    |  (zero LLM cost if    |\n    |   no pronouns found)  |\n    +-----------+-----------+\n                | pronouns detected\n    +-----------v-----------+\n    |  Tier 1: Self-Check   |\n    |  Single haiku call    |\n    |  Returns confidence   |\n    +-----------+-----------+\n                | confidence < threshold?\n           yes  |           | no\n    +-----------v---+   +---v-----------+\n    |  Tier 2:      |   |  Substitute   |\n    |  Council      |   |  silently     |\n    |  3 haiku      |   +---------------+\n    |  agents vote  |\n    +-------+-------+\n            |\n       majority?\n      yes   |     no\n    +---v---+ +---v-----------+\n    | Sub.  | | Ask the user  |\n    +-------+ +---------------+\n            |\n    +-------v-----------+\n    |  Claude receives:  |\n    |  [Pronoun Resolution: \"it\" -> \"auth middleware in src/server.ts\"]  |\n    |  fix it            |\n    +--------------------+\n```\n\nThe original message is never modified. Claude receives a disambiguation preamble alongside your prompt.\n\n## Detection: What Gets Flagged\n\n**Target pronouns:** `it`, `them`, `these`, `those`, `that`, `this`, `they`, `its`\n\nThe skill doesn't blindly flag every pronoun. It checks whether the prompt is **self-contained** -- whether it has enough nouns and specifics to resolve its own pronouns.\n\n### Flagged (ambiguous -- needs resolution)\n\n| Prompt | Why |\n|--------|-----|\n| `fix it` | \"it\" has no referent in the message |\n| `is it possible` | standalone question, \"it\" refers to prior context |\n| `that's correct` | standalone affirmation, \"that\" references something |\n| `update them` | \"them\" could be anything |\n| `take that and apply it to these` | three chained pronouns, all ambiguous |\n\n### Not flagged (self-contained -- passes through)\n\n| Prompt | Why |\n|--------|-----|\n| `fix it in the auth handler` | \"it\" is qualified by \"in the auth handler\" |\n| `is it possible to add retry logic` | full context provided |\n| `that's correct, now refactor the parser` | \"that\" is structural, real instruction is clear |\n| `update these test files` | \"these\" immediately followed by \"test files\" |\n| `refactor the auth handler in server.ts` | no pronouns at all |\n\n### Edge cases\n\n**Multiple pronouns:** `\"Fix it and update them\"` -- each resolved independently. If only one falls below the confidence threshold, only that one escalates to the council. The confident one substitutes immediately.\n\n**Chained references:** `\"Take that and apply it to these\"` -- resolved left-to-right. \"that\" first, then \"it\" (which may now reference the resolved \"that\"), then \"these.\"\n\n**Idiomatic uses:** `\"Let it crash\"`, `\"this is fine\"` -- the self-check recognizes genuine idioms and skips them. The ledger tracks these patterns so false positive rates decrease over time.\n\n## Tiered Resolution Engine\n\n### Tier 1: Quick Self-Check\n\nA single haiku-tier LLM call. Fast, cheap. Gets your message plus recent context and returns a structured resolution with a confidence score (0.0-1.0).\n\n```json\n{\n  \"pronoun\": \"it\",\n  \"referent\": \"the auth middleware in src/server.ts\",\n  \"confidence\": 0.92,\n  \"context_signal_used\": \"last_edited_file\",\n  \"idiomatic\": false\n}\n```\n\nIf confidence >= the adaptive threshold (default 0.8), the resolution is accepted and injected silently.\n\n### Tier 2: Council Vote\n\nTriggered only when Tier 1 confidence is below threshold. Spawns 3 independent haiku subagents. Each resolves the pronoun independently -- they don't see each other's answers (prevents anchoring bias).\n\n- **2/3 agree:** majority wins, substitute silently\n- **All 3 disagree:** falls back to asking you directly via AskUserQuestion (the only time the skill breaks silence)\n\n### Why tiered?\n\nMost pronouns are easy. \"fix it\" after you just edited one file? Haiku resolves that at 0.95 confidence in under a second. The council only fires for genuinely ambiguous cases, saving tokens and latency.\n\n## Self-Learning Ledger\n\nEvery resolution is logged to `.claude/pronoun-ledger.json` in your project directory. The ledger tracks three things:\n\n### 1. Resolution History\n\n```json\n{\n  \"timestamp\": \"2026-05-24T14:30:00Z\",\n  \"pronoun\": \"it\",\n  \"original_prompt\": \"fix it\",\n  \"resolved_to\": \"the auth middleware in src/server.ts\",\n  \"tier_used\": \"self-check\",\n  \"confidence\": 0.92,\n  \"context_signal_used\": \"last_edited_file\",\n  \"was_corrected\": false\n}\n```\n\nIf you correct the resolution (e.g., \"no not that, I meant the database migration\"), `was_corrected` flips to `true` and the ledger learns from the mistake.\n\n### 2. Context Reliability Scores\n\nTracks which context signals produce accurate resolutions for your project:\n\n```json\n{\n  \"last_edited_file\": 0.85,\n  \"last_tool_call\": 0.72,\n  \"conversation_topic\": 0.45,\n  \"recent_symbol\": 0.63\n}\n```\n\nScores update via exponential moving average (alpha=0.2). The self-check prompt receives these scores and weights more reliable signals higher.\n\n### 3. Adaptive Threshold\n\nStarts at 0.8. Recalculates every 10 resolutions:\n\n| Self-check accuracy | Threshold change | Effect |\n|---------------------|------------------|--------|\n| > 90% | drops 0.05 (min 0.6) | Trusts self-check more, fewer council calls |\n| 75-90% | no change | Stays the course |\n| < 75% | rises 0.05 (max 0.95) | Escalates to council more often |\n\nA project where you always mean \"the last file I edited\" will quickly learn to resolve confidently without the council. A project with ambiguous naming conventions will stay conservative.\n\n### Correction Detection\n\nThe skill watches your follow-up messages for correction signals:\n\n- Explicit: \"no not that\", \"I meant X\", \"wrong file\"\n- Redirections: \"the other one\", \"I was talking about Y\"\n- Frustration: \"why are you looking at X\"\n\nWhen detected, the most recent resolution is marked as corrected and the context reliability score for the signal that was used gets downgraded.\n\n### Maintenance\n\nEntries older than 30 days are pruned automatically on session startup. The ledger stays small -- a few hundred entries max for an active project.\n\n## File Structure\n\n```\npronoun-resolver/\n  SKILL.md                       # Skill definition + hook wiring\n  bin/\n    detect-pronouns.sh           # Hook entry point -- regex scan + orchestration\n    resolve.sh                   # Tiered resolution engine\n    ledger.sh                    # Ledger read/write/prune/threshold utilities\n  prompts/\n    self-check.md                # Tier 1 prompt template\n    council-agent.md             # Tier 2 prompt template (per subagent)\n    correction-detector.md       # Post-resolution correction detection prompt\n```\n\n## Install\n\n### From ClaWHub (recommended)\n\n```bash\nclawhub install pronoun-resolver\n```\n\n### From GitHub\n\n```bash\ngit clone https://github.com/kaicianflone/coding-pronoun-prompt-resolver.git\nln -s \"$(pwd)/coding-pronoun-prompt-resolver\" ~/.claude/skills/pronoun-resolver\n```\n\n### Manual\n\nCopy the entire directory to `~/.claude/skills/pronoun-resolver`.\n\nThe skill activates immediately. The `user-prompt-submit` hook fires on every message automatically.\n\n## Configuration\n\n### Disable for a project\n\n```bash\nmkdir -p .claude\ntouch .claude/pronoun-resolver-disabled\n```\n\n### Re-enable\n\n```bash\nrm .claude/pronoun-resolver-disabled\n```\n\n### Reset the ledger\n\n```bash\nrm .claude/pronoun-ledger.json\n```\n\nThe ledger will be re-created on the next resolution with default settings (threshold 0.8, all context signals at 0.5).\n\n### Gitignore\n\nAdd to your project's `.gitignore`:\n\n```\n.claude/pronoun-ledger.json\n.claude/pronoun-resolver-disabled\n```\n\nThe ledger is per-developer, per-project. It should not be committed.\n\n## Requirements\n\n- Claude Code CLI v2.0+ (`claude` command in PATH)\n- Python 3.6+\n- Bash 4+\n\n## How It Differs From System Prompt Instructions\n\nYou could add \"don't use pronouns\" to your system prompt. But that:\n- Only works if Claude follows the instruction (it often doesn't for short prompts)\n- Doesn't resolve what the pronoun actually means\n- Doesn't learn from your patterns over time\n- Adds to every prompt's token cost whether or not pronouns are present\n\nThis skill intercepts at the input layer, resolves concretely, costs nothing when there are no pronouns, and gets better over time.\n\n## License\n\nMIT\n\nFile v0.1.0:_meta.json\n\n{\n  \"ownerId\": \"kn7aakh8bj9gfbh6ah7rtw6pf180g5qr\",\n  \"slug\": \"pronoun-resolver\",\n  \"version\": \"0.1.0\",\n  \"publishedAt\": 1779605069173\n}\n\nFile v0.1.0:prompts/correction-detector.md\n\nYou are checking whether a user's follow-up message indicates they are correcting a previous pronoun resolution.\n\n## Input\n\nPrevious resolution: \"{{PRONOUN}}\" was resolved to \"{{RESOLVED_TO}}\"\n\nUser's follow-up message: {{USER_MESSAGE}}\n\n## Instructions\n\nDoes this follow-up message indicate the user is correcting the resolution? Look for:\n- Explicit corrections: \"no not that\", \"I meant X\", \"wrong file\", \"not that one\"\n- Redirections: \"the other one\", \"I was talking about X\", \"no, the Y\"\n- Frustration with wrong target: \"why are you looking at X\", \"that's not what I said\"\n\nDo NOT flag as correction:\n- New instructions unrelated to the resolution\n- Agreement or continuation (\"yes\", \"good\", \"now do X\")\n- Questions about the resolved target\n\n## Output\n\nReturn ONLY valid JSON, no markdown fences:\n\nIf correction: {\"is_correction\": true, \"corrected_referent\": \"what the user actually meant\"}\n\nIf not: {\"is_correction\": false}\n\nFile v0.1.0:prompts/council-agent.md\n\nYou are one of three independent judges resolving an ambiguous pronoun. You must determine what the pronoun refers to based solely on the context provided. Do NOT hedge or give multiple options. Commit to your best answer.\n\n## Input\n\nUser message: {{USER_MESSAGE}}\n\nPronoun to resolve: {{PRONOUN}}\n\nRecent conversation context (last 3-5 messages):\n{{CONVERSATION_CONTEXT}}\n\n## Instructions\n\nDetermine the single most likely referent for \"{{PRONOUN}}\" in the user's message. Be specific: name the file, function, variable, concept, or entity.\n\n## Output\n\nReturn ONLY valid JSON, no markdown fences, no explanation:\n\n{\"pronoun\": \"{{PRONOUN}}\", \"referent\": \"the specific thing it refers to\", \"confidence\": 0.85}\n\nFile v0.1.0:prompts/self-check.md\n\nYou are a pronoun resolver. Your job is to determine what ambiguous pronouns refer to in a user's message, given recent conversation context.\n\n## Input\n\nUser message: {{USER_MESSAGE}}\n\nDetected pronouns: {{PRONOUNS}}\n\nRecent conversation context (last 3-5 messages):\n{{CONVERSATION_CONTEXT}}\n\nContext reliability scores (higher = more reliable signal):\n{{CONTEXT_RELIABILITY}}\n\n## Instructions\n\nFor each detected pronoun, determine:\n1. What it most likely refers to (the \"referent\")\n2. How confident you are (0.0 to 1.0)\n3. Whether it's idiomatic/structural (not referencing a specific code entity)\n\nWeight your resolution toward context signals with higher reliability scores.\n\nIf the prompt is self-contained (the pronoun is immediately qualified by a noun, e.g., \"fix this function\"), mark it as idiomatic with confidence 0.99.\n\nFor chained pronouns (e.g., \"take that and apply it to these\"), resolve left-to-right. Later pronouns may reference earlier resolved ones.\n\n## Output\n\nReturn ONLY valid JSON, no markdown fences, no explanation:\n\n{\"resolutions\": [{\"pronoun\": \"it\", \"referent\": \"the specific thing it refers to\", \"confidence\": 0.92, \"context_signal_used\": \"last_edited_file\", \"idiomatic\": false}]}\n\nIf idiomatic:\n\n{\"resolutions\": [{\"pronoun\": \"it\", \"referent\": \"N/A\", \"confidence\": 0.99, \"context_signal_used\": \"none\", \"idiomatic\": true}]}","readmeExcerpt":"Skill: Coding Pronoun Prompt Resolver Owner: kaicianflone Summary: Detects ambiguous pronouns, vague referents, and bare imperatives in user messages and flags them for resolution using conversation context. Zero-latency det... Tags: latest:0.11.0 Version history: v0.11.0 | 2026-05-31T16:09:22.001Z | user Always-on logging directive + locked, sanitizing ledger writer (bin/log-resolution.py). Secret/PII redaction, hex","codeSnippets":[],"executableExamples":[{"language":"text","snippet":"[PRONOUN-RESOLVER: Resolve these using conversation context. HIGH confidence=act silently. MEDIUM=state assumption then act. LOW/no context=ask user first.]\n[AMBIGUOUS: pronouns=\"it,that\" | type=pronoun]\n[AMBIGUOUS: vague=\"other,something\" | type=vague_referent]\n[AMBIGUOUS: implicit verb=\"make\" | type=bare_imperative | subtype=verb_adjective]"},{"language":"json","snippet":"{\n  \"resolutions\": [...],\n  \"resolution_count\": 0,\n  \"adaptive_threshold\": 0.8,\n  \"context_reliability\": {}\n}"},{"language":"json","snippet":"{\n  \"timestamp\": \"ISO8601\",\n  \"pronoun\": \"it\",\n  \"prompt_hash\": \"sha256 hex of the full prompt (no raw text stored)\",\n  \"resolved_to\": \"the auth middleware\",\n  \"tier_used\": \"green|yellow|red|black\",\n  \"confidence\": 0.92,\n  \"was_corrected\": false\n}"},{"language":"json","snippet":"\"UserPromptSubmit\": [\n  {\n    \"hooks\": [\n      {\n        \"type\": \"command\",\n        \"command\": \"bash /ABSOLUTE/PATH/TO/.claude/skills/pronoun-resolver/bin/detect-pronouns.sh\"\n      }\n    ]\n  }\n]"},{"language":"text","snippet":"User types: \"fix it\"\n                |\n    +-----------v-----------+\n    |  Hook: detect-pronouns |\n    |  (regex + heuristic)   |\n    |  ~0ms, no LLM calls    |\n    +-----------+-----------+\n                | ambiguity detected\n    +-----------v-----------+\n    |  Output: flags +       |\n    |  compact preamble      |\n    +-----------+-----------+\n                |\n    +-----------v-----------+\n    |  Claude receives:      |\n    |  [PRONOUN-RESOLVER: Resolve using context. HIGH=act. LOW=ask.]  |\n    |  [AMBIGUOUS: pronouns=\"it\" | type=pronoun]                      |\n    |  fix it                |\n    +--------------------+---+\n                |\n    +-----------v-----------+\n    |  Claude resolves using |\n    |  conversation context  |\n    |  (GREEN/YELLOW/RED)    |\n    +------------------------+"},{"language":"json","snippet":"{\n  \"resolutions\": [],\n  \"resolution_count\": 0,\n  \"adaptive_threshold\": 0.8,\n  \"context_reliability\": {}\n}"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: pronoun-resolver\nversion: 0.11.0\ndescription: |\n  Detects ambiguous pronouns, vague referents, and bare imperatives in user messages\n  and flags them for resolution using conversation context. Zero-latency detection via\n  hook; resolution happens inside the conversation where context lives. Self-learning\n  via correction ledger with adaptive confidence tiering.\ncapabilities:\n  - user-prompt-submit hook (fires on every message, regex-only, no LLM calls)\n  - file-write: ~/.claude/skills/pronoun-resolver/.claude/pronoun-ledger.json (resolution metadata, no raw prompts)\n  - file-write: ~/.claude/skills/pronoun-resolver/.claude/pronoun-resolver-analytics.jsonl (per-message stats)\ndata_retention: |\n  All data is local-only, never transmitted externally. Prompts are hashed (SHA-256),\n  never stored as text. Both data files can be deleted without affecting functionality.\nhooks:\n  user-prompt-submit:\n    - type: command\n      command: \"bash ${CLAUDE_SKILL_DIR}/bin/detect-pronouns.sh\"\n      statusMessage: \"Scanning for ambiguous references...\"\n---\n\n# Pronoun Resolver\n\n## Arguments\n\nIf invoked with `--stats`: run `python3 ~/.claude/skills/pronoun-resolver/bin/stats.py` and display the output. Do not proceed with the rest of this skill.\n\n---\n\nYou are operating with the pronoun resolver active. When the hook detects ambiguous\nreferences in a user message, you will see flags injected before the message.\n\n## Your Role\n\nYOU are the resolver. You have the conversation context. The hook just detects — you decide.\n\n## Resolution Tiering\n\nWhen you see `[AMBIGUOUS:]` flags, apply this framework:\n\n### GREEN — Resolve silently (90%+ confidence)\nThe referent is obvious from the last 1-3 messages. Just act. Don't mention the resolution.\n- \"Fix it\" when you just showed them a bug → fix the bug\n- \"Make that work\" after discussing a failing test → fix the test\n\n### YELLOW — State assumption, proceed (70-90% confidence)\nYou're fairly sure but there's ambiguity. State what you're assuming in one line, then act.\n- \"I'm taking 'the other one' to mean `auth.ts` since we discussed two files. Acting on that.\"\n\n### RED — Ask before acting (<70% confidence)\nMultiple plausible referents, or no recent context to resolve against. Ask concisely.\n- \"What should I make good — the UI layout we discussed or the API response format?\"\n\n### BLACK — Bare imperative, no context at all\nFirst message of a conversation with no object. Always ask.\n- \"Make good\" with no prior context → \"What would you like me to improve?\"\n\n## Flag Format\n\nThe hook outputs a preamble followed by flags:\n```\n[PRONOUN-RESOLVER: Resolve these using conversation context. HIGH confidence=act silently. MEDIUM=state assumption then act. LOW/no context=ask user first.]\n[AMBIGUOUS: pronouns=\"it,that\" | type=pronoun]\n[AMBIGUOUS: vague=\"other,something\" | type=vague_referent]\n[AMBIGUOUS: implicit verb=\"make\" | type=bare_imperative | subtype=verb_adjective]\n```\n\n## Ledger\n\nResolution accuracy is tracked at `~/.claude/ski"},{"path":"README.md","content":"# Pronoun Resolver\n\nA Claude Code hook that detects ambiguous references in user prompts and flags them for resolution. Zero-latency detection via regex/heuristics — Claude resolves using its own conversation context.\n\nNo LLM calls. No external API keys. Fires on every message, produces output only when ambiguity is detected.\n\n## The Problem\n\nWhen you type \"fix it\", Claude has to guess what \"it\" refers to. Sometimes it guesses right. Sometimes it confidently refactors the wrong file.\n\nWhen you type \"Make good\" with no context, Claude may invent an interpretation rather than asking.\n\nThis hook makes the ambiguity visible so Claude asks instead of guessing.\n\n## How It Works\n\n```\nUser types: \"fix it\"\n                |\n    +-----------v-----------+\n    |  Hook: detect-pronouns |\n    |  (regex + heuristic)   |\n    |  ~0ms, no LLM calls    |\n    +-----------+-----------+\n                | ambiguity detected\n    +-----------v-----------+\n    |  Output: flags +       |\n    |  compact preamble      |\n    +-----------+-----------+\n                |\n    +-----------v-----------+\n    |  Claude receives:      |\n    |  [PRONOUN-RESOLVER: Resolve using context. HIGH=act. LOW=ask.]  |\n    |  [AMBIGUOUS: pronouns=\"it\" | type=pronoun]                      |\n    |  fix it                |\n    +--------------------+---+\n                |\n    +-----------v-----------+\n    |  Claude resolves using |\n    |  conversation context  |\n    |  (GREEN/YELLOW/RED)    |\n    +------------------------+\n```\n\nClaude is the resolver. It has the conversation context. The hook just makes ambiguity explicit.\n\n## Detection Categories\n\n### 1. Personal Pronouns (always flagged)\n\n`it`, `them`, `they`, `its`\n\nThese are always referential — they can't be determiners.\n\n### 2. Demonstratives (smart filtering)\n\n`this`, `that`, `these`, `those`\n\nOnly flagged when used as standalone pronouns, NOT as determiners:\n\n| Prompt | Flagged? | Why |\n|--------|----------|-----|\n| `fix this` | Yes | \"this\" is standalone, no object |\n| `fix this bug` | No | \"this\" is a determiner for \"bug\" |\n| `do that and deploy` | Yes | \"that\" followed by conjunction |\n| `update that file` | No | \"that\" is a determiner for \"file\" |\n| `these tests are failing` | No | \"these\" is a determiner for \"tests\" |\n\n### 3. Vague Referents\n\n`other`, `something`, `someone`, `somewhere`, `anything`, `everything`, `stuff`\n\n### 4. Bare Imperatives (implicit subject)\n\nDetected when no pronouns or vague words are found. Catches commands with no explicit object:\n\n| Prompt | Detected | Subtype |\n|--------|----------|---------|\n| `Fix` | Yes | bare_verb |\n| `Make good` | Yes | verb_adjective |\n| `Make better/faster` | Yes | verb_adjective |\n| `Clean up` | Yes | verb_adjective |\n| `Fix the bug` | No | has explicit object |\n| `Add tests` | No | has noun object |\n\n## Resolution Tiering\n\nWhen Claude sees flags, it applies this framework:\n\n| Tier | Confidence | Action |\n|------|-----------|--------|\n| GREEN | 90%+ | Resolve silently, just act |\n| YE"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn7aakh8bj9gfbh6ah7rtw6pf180g5qr\",\n  \"slug\": \"pronoun-resolver\",\n  \"version\": \"0.11.0\",\n  \"publishedAt\": 1780243762001\n}"},{"path":"CHANGELOG.md","content":"# Changelog\n\nAll notable changes to the Pronoun Resolver skill are documented here.\n\n## [0.11.0] - 2026-05-31\n\n### Added\n- **Always-present logging directive.** The hook now injects a\n  `[PRONOUN-RESOLVER-LOG: ...]` directive on every flagged message, carrying the\n  exact `bin/log-resolution.py` command and ledger path. The hook prints the\n  directive; Claude runs it to record a resolution. The directive is now in\n  context on every fire even when `SKILL.md` isn't loaded (previously the logging\n  instruction lived only in the skill body, so the ledger almost never updated).\n- **`bin/log-resolution.py`** — a locked, sanitizing ledger writer that owns all\n  ledger mutations.\n- **`tests/test_log_resolution.py`** — dependency-free unit tests for the\n  sanitizer, ledger I/O, validation, and concurrency.\n\n### Security\n- **Secret/PII redaction** on every free-text field before it touches disk:\n  API keys, tokens (OpenAI/Stripe/GitHub/GitLab/Slack/npm/Google), JWTs, PEM\n  private keys, credentials in DB URLs, Bearer/Basic auth, emails, SSNs, phone\n  numbers, and long hex/base64 blobs. Control characters (except tab/newline)\n  stripped; over-long values truncated.\n- **`prompt_hash` validated** as a hex digest (raw text is dropped), and the\n  emitted hook directive single-quotes install-derived paths so a checkout path\n  containing shell metacharacters can't become executable syntax.\n\n### Fixed\n- **Concurrency race:** ledger writes now run under an exclusive `flock` across\n  the full read-modify-write, so parallel hook fires no longer drop entries.\n- **Corruption safety:** a non-empty ledger that can't be parsed (or isn't the\n  expected object shape) is backed up to `*.corrupt` instead of being silently\n  overwritten; `confidence` is clamped to `[0,1]` (non-finite → `0.5`) and the\n  writer refuses to emit `NaN`/`Infinity` (`allow_nan=False`)."},{"path":"skill-card.md","content":"## Description:\n\nDetects ambiguous pronouns, vague referents, and bare imperatives in user messages and flags them for resolution using conversation context.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[kaicianflone](https://clawhub.ai/user/kaicianflone)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and coding-agent users use this skill to make ambiguous prompts visible before an agent guesses the wrong referent. It guides the agent to resolve high-confidence references from conversation context, state assumptions for moderate confidence, or ask before acting when context is weak.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The hook runs on every submitted prompt and scans prompt text locally.\n\nMitigation: Install only where this behavior is acceptable, and use the documented project disable sentinel when prompt scanning should be inactive.\n\nRisk: The skill keeps local analytics and a resolution ledger under the skill directory.\n\nMitigation: Review the stored fields and delete the ledger or analytics files when retained metadata is no longer wanted.\n\nRisk: Stored free-text resolution metadata may still contain novel secret formats or plain-language personal data despite pattern-based redaction.\n\nMitigation: Avoid logging sensitive referents, review retained metadata periodically, and clear the local files for sensitive projects.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/kaicianflone/skills/pronoun-resolver)\n- [Publisher profile](https://clawhub.ai/user/kaicianflone)\n- [README](artifact/README.md)\n- [Changelog](artifact/CHANGELOG.md)\n- [Evaluation results](artifact/evals/results.json)\n\n## Skill Output:\n\n**Output Type(s):** [Text, Markdown, Shell commands, Configuration, Guidance]\n\n**Output Format:** [Markdown guidance with inline shell commands and local hook output flags]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Runs locally as a user-prompt-submit hook; stores local analytics and resolution metadata when the agent records a resolution.]\n\n## Skill Version(s):\n\n0.11.0 (source: SKILL.md frontmatter and release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment."}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"Detects ambiguous pronouns, vague referents, and bare imperatives in user messages and flags them for resolution using conversation context. Zero-latency det... Skill: Coding Pronoun Prompt Resolver Owner: kaicianflone Summary: Detects ambiguous pronouns, vague referents, and bare imperatives in user messages and flags them for resolution using conversation context. Zero-latency det... Tags: latest:0.11.0 Version history: v0.11.0 | 2026-05-31T16:09:22.001Z | user Always-on logging directive + locked, sanitizing ledger writer (bin/log-resolution.py). Secret/PII redaction, hex","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":1783,"uniquenessScore":46,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-11T16:57:57.727Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-11T16:57:57.727Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-11T20:59:39.941Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}