What This Is

find-your-knowns is a Markdown-first agent skill for Claude Code, OpenAI Codex, Cursor, and other skill-aware coding agents.

It helps agents find hidden requirements before they guess: unfamiliar codebase constraints, vague product taste, risky API or data decisions, plan-vs-reality drift, reviewer objections, and merge-time understanding gaps.

It does not require the user to know what they are missing. The trigger is the shape and blast radius of the task: under-specified implementation, auth, billing, migrations, data, APIs, security, UX taste, references, or large plans.

The package uses one router skill plus focused reference workflows. The router lives at skills/find-your-knowns/SKILL.md; each workflow is loaded only when relevant.

Source idea: Thariq Shihipar's public essay "A Field Guide to Fable: Finding Your Unknowns" and companion "Know your unknowns" artifact gallery.

Why Use It

Use this skill when a coding task is vague, under-specified, high-stakes, design-heavy, reference-based, long-running, or expensive to redo.

Skip it for tiny direct changes, ordinary code review, bug review, security review, and PR defect-finding. Those need review-specific methods, not unknown-discovery routing.

Workflows

| Phase | Workflow | Use it for | | --- | --- | --- | | Before | Blindspot pass | Hidden constraints in unfamiliar code or domains | | Before | Teach me my unknowns | Missing vocabulary, standards, and quality criteria | | Before | Design directions | Divergent UX, product, or visual directions | | Before | Mock before wire | Throwaway shape validation before real implementation | | Before | Effort-axis brainstorm | Options ranked by effort, risk, and proof | | Before | Interview | One high-impact decision question at a time | | Before | Reference hunt | Preserve behavior from existing code, products, or specs | | Before | Tweakable plan | Implementation plans ordered by likely user veto | | During | Implementation notes | Scoped plan-vs-reality decisions during execution | | After | Buy-in doc | Reviewer and stakeholder understanding | | After | Change quiz | Pre-merge comprehension of a large change |

What Makes This Package Different

• Full 11-workflow coverage without requiring interactive HTML artifacts.
• Explicit trigger guard against hijacking normal code review or security review.
• Scoped implementation notes that avoid random repo-root files.
• Skill-folder LICENSE, so manual installs preserve license metadata.
• Agent-agnostic Markdown: useful as a formal skill or plain instructions.

Install

Fast path with npm:

npx find-your-knowns install ~/.codex/skills

For Cursor projects:

npx find-your-knowns cursor .

Manual git path:

git clone https://github.com/aiswarya797/find-your-knowns.git
mkdir -p "<agent-skills-dir>"
cp -R "find-your-knowns/skills/find-your-knowns" "<agent-skills-dir>/"

Then ask your agent:

Use find-your-knowns before planning this feature.

Install details:

• Claude Code, Codex/manual loading, Cursor, and instruction-only agents: docs/install.md
• Cursor always-on router rule: .cursor/rules/find-your-knowns.mdc

For instruction-only agents, load:

skills/find-your-knowns/SKILL.md

For repo-local use, keep this repository in your project and invoke:

Use the workflow at find-your-knowns/skills/find-your-knowns before planning this feature.

Examples

Prompts:

Use find-your-knowns. I need to add passkey login, but I have not worked in this auth module before.

Use find-your-knowns. Make this dashboard feel cleaner and more production-ready, but show me directions before wiring anything.

Use find-your-knowns. Recreate the retry semantics from vendor/rate-limiter in our TypeScript client, but prove you understood the reference first.

Use find-your-knowns. The migration plan assumed one account per workspace, but the schema allows many.

Use find-your-knowns. Explain this branch before merge and quiz me on the risks.

Sample outputs:

• Blindspot pass
• Design directions
• Reference hunt
• Implementation notes
• Buy-in doc
• Change quiz

Templates

Reusable short templates live in templates/:

• Blindspot pass
• Design directions
• Reference hunt
• Implementation notes
• Buy-in doc
• Change quiz

Package Layout

find-your-knowns/
  README.md
  LICENSE
  assets/
    logo.svg
  docs/
    install.md
  examples/
  templates/
  bin/
    find-your-knowns.mjs
  .cursor/rules/
  skills/
    find-your-knowns/
      LICENSE
      SKILL.md
      references/
        <focused workflows loaded by SKILL.md>

Validation

npm run validate

Validation runs markdown lint, stale package-slug checks, and git diff --check.

Source And Attribution

This package is an original implementation inspired by Thariq Shihipar's unknowns framing. Read the source material first if you want the full reasoning:

• A Field Guide to Fable: Finding Your Unknowns
• Know your unknowns companion artifacts

The workflow text, templates, examples, package layout, and CLI here are original. Credit the source idea when producing reusable artifacts; do not copy Thariq's source text or artifacts.

License

MIT. See LICENSE.