# Prompt Library by Kika (akakika.com)

> 286 copy-paste prompts for working with AI coding agents: reviewing a run, planning, building and shipping, native macOS interaction, keyboard and commands, layout, data safety, and docs. Free and open. Browse and copy them at https://akakika.com/prompts

Author: Kika (https://akakika.com/about). More tools: https://github.com/aka-kika

## Categories

- Review & Planning (37)
- Build & Ship (25)
- Design & UI (34)
- Platform & Infra (22)
- Docs & Continuity (17)
- Snippets (1)
- Cogito Notes (11)
- Agent Prompts (38)
- Claude Library (33)
- Commands & Keyboard (13)
- macOS Interaction (11)
- Layout & Windowing (13)
- Data Safety & State (16)
- System & Platform (15)

---

## Review & Planning

### After-Run Review

> Strictly review what the last run actually changed — before asking the agent to continue.

**When to use:** Immediately after Agent finishes a task, before asking it to continue. Catches accidental changes, bad assumptions, or incomplete work.

#### Prompt
```text
Review the changes from the last run.

Check:
- what changed
- whether the change matches the task
- bugs or regressions
- files that should not have changed
- docs that now need updating
- the next safest step

Be strict. Do not assume the run succeeded.
```

### Agent Project Planning

> Make a task agent-ready before a run — specific, scoped, and clear about what not to touch.

**When to use:** Before sending a project or task to Agent, especially when the repo is messy or the task might be too broad.

#### Prompt
```text
Review this project before I send it to Agent. Identify:
- unclear requirements
- missing files Agent will need
- likely hallucination points
- places where Agent may overbuild
- the best first step
```

#### Variations
**Make it Agent-ready:**
```text
Convert this into an Agent-ready task. Make it:
- specific
- step-by-step
- small enough for one run
- clear about files to edit
- clear about what NOT to change
```

**Senior-engineer critique:**
```text
Act as a senior engineer reviewing this Agent prompt. Tell me:
- what is ambiguous
- what needs constraints
- what should be split into separate runs
- what is risky
- how to rewrite it for better output
```

### AI Workflow Review

> Tighten an agent workflow — reduce freedom and vagueness, add stop conditions.

**When to use:** Designing AI agents, automation flows, MCP workflows, or Agent multi-step behavior.

#### Prompt
```text
Review this AI workflow and identify:
- where the agent has too much freedom
- where instructions are vague
- where hallucinations are likely
- what should be deterministic
- what should require user confirmation
```

#### Variations
**Make it safer & more reliable:**
```text
Make this agent workflow safer and more reliable. Identify:
- inputs it needs
- outputs it must produce
- rules it must follow
- things it must never change
- checkpoints where it should stop
```

**Turn a messy idea into a controlled workflow:**
```text
Turn this messy agent idea into a controlled workflow:
- trigger
- inputs
- steps
- output format
- failure cases
- stop conditions
```

### App Idea Validation

> Be skeptical before committing time — who needs it, what exists, why it might fail.

**When to use:** Before committing time to a new app, especially if the idea sounds exciting but unclear.

#### Prompt
```text
Review this app idea and be skeptical. Tell me:
- who actually needs it
- what problem it solves
- what already exists
- why someone would use this instead
- what makes the idea weak
```

#### Variations
**Stress-test before building:**
```text
Stress-test this idea before I build it. Identify:
- weak assumptions
- unclear users
- features that hide the real problem
- reasons it may fail
- the smallest test I can run first
```

**Skeptical indie reviewer:**
```text
Act as a skeptical indie app reviewer. Tell me:
- what is compelling
- what is generic
- what is too vague
- what should be cut
- what would make this worth building
```

### Architecture Review

> Spot fake scalability and premature structure before you commit to it.

**When to use:** Before creating folders, modules, services, databases, sync systems, or complex "future-proof" structures.

#### Prompt
```text
Review this architecture and identify:
- fake scalability
- premature modularization
- unnecessary services
- places where local-first would be simpler
- the minimum architecture for v1
```

#### Variations
**Indie-app reviewer:**
```text
Act as an architecture reviewer for a small indie app. Tell me:
- what is too enterprise
- what can be a simple local file/database
- what should not be networked yet
- what should stay hardcoded for v1
- what is the cleanest simple structure
```

**Challenge — assume I'm overbuilding:**
```text
Challenge this architecture. Assume I am overbuilding. Identify:
- needless layers
- abstractions without current value
- risky dependencies
- complexity that does not help the user
- a simpler alternative
```

### Before I Build

> The default pre-build review — find the real core problem and the smallest useful version before writing anything.

**When to use:** As the default review prompt before starting any new app, feature, automation, agent, or Agent project.

#### Prompt
```text
Before I build this, review it like a strict solo-developer advisor. Identify:
- the real core problem
- the smallest useful version
- what is overbuilt
- what should be delayed
- what can be manual
- what risks wasting time
- the best first 3 tasks
```

#### Notes
- Master pre-build gate — pairs well with Simplicity Review and One-Feature MVP right after.

### Bug Fix Without Refactor

> Fix one bug and nothing else — no redesign, no renames, no architecture changes.

**When to use:** When you want one bug fixed without Agent redesigning the app, renaming files, or changing architecture.

#### Prompt
```text
Fix only the described bug.

Rules:
- do not refactor unrelated code
- do not rename files
- do not change architecture
- do not add new features
- keep the fix minimal
- explain the root cause
- list exactly what changed
```

### Code Review

> Catch over-cleverness, duplication, and hidden bugs before moving on.

**When to use:** After Agent writes code, before continuing to the next feature, or when the code feels too clever.

#### Prompt
```text
Review this code and identify:
- unnecessary abstraction
- duplicated logic
- confusing naming
- hidden bugs
- places where a simpler implementation would be better
```

#### Variations
**Strict Swift/macOS reviewer:**
```text
Act as a strict Swift/macOS code reviewer. Look for:
- non-native patterns
- overcomplicated state
- fragile logic
- unnecessary dependencies
- places to simplify before adding features
```

**Solo-maintainer quality:**
```text
Review this code for solo-maintainer quality. Identify:
- what will be hard to debug later
- what is too clever
- what should be renamed
- what should be deleted
- what should be documented
```

### Feature Prioritization

> Sort a feature list into build-now / later / never, with reasons.

**When to use:** You have many possible features and need to decide what belongs in v1, v2, or "not now."

#### Prompt
```text
Review this feature list and sort it into:
- build now
- build later
- probably never
- only if users ask
- dangerous distraction
Explain why.
```

#### Variations
**PM with a shipping bias:**
```text
Act as a product manager with a bias for shipping. Review these features and tell me:
- what creates real value
- what only sounds useful
- what increases maintenance
- what delays launch
- what the v1 roadmap should be
```

**Solo-dev roadmap:**
```text
Prioritize this roadmap for a solo developer. Consider:
- build time
- maintenance cost
- user value
- complexity
- risk of rabbit holes
Return a practical v1/v2/v3 plan.
```

### Find Dead Code

> Inspect a project for dead code, duplication, and stale cruft — and report before deleting anything.

**When to use:** After many Agent runs, after a feature is removed, or when the repo feels messy.

#### Prompt
```text
Inspect the project for cleanup opportunities.

Identify:
- dead code
- unused files
- duplicate logic
- stale TODOs
- outdated comments
- unnecessary abstractions
- files that can be simplified

Do not delete anything yet. First report findings and suggest a safe cleanup plan.
```

### Keep This App Focused

> Pull an app back to its one job — cut the tabs, panels, and "nice" ideas that weaken its purpose.

**When to use:** When an app starts growing too many tabs, panels, dashboards, or "nice" ideas that weaken the original purpose.

#### Prompt
```text
Review this app and bring it back to its core purpose.

Identify:
- the original main job of the app
- features that support that job
- features that distract from it
- screens or tabs that should be removed, merged, or delayed
- what the app should do in the first 30 seconds
- the simplest version that still feels useful

Rules:
- keep the app focused
- avoid dashboard bloat
- do not add new features
- prefer one clear workflow over many weak sections
- suggest what to cut before suggesting what to add
```

### Make Project Understandable

> Make a repo clear for a new developer — improve only what aids understanding, no marketing copy.

**When to use:** Before sharing a repo, creating a zip, handing off to another agent, or reopening a project after time away.

#### Prompt
```text
Make this project understandable for a new developer.

Check:
- README clarity
- folder structure
- setup instructions
- main entry points
- important files
- missing explanations
- confusing names

Update only what improves understanding.
Do not add marketing copy.
```

### Next 3 Tasks Only

> Cut the noise to the next 3 useful tasks — no full roadmap, no speculative features.

**When to use:** When a project has too many possible next steps and you need a focused continuation plan.

#### Prompt
```text
Based on the current project state, identify only the next 3 useful tasks.

For each task include:
- why it matters
- files likely involved
- expected result
- what not to expand into

Do not create a full roadmap.
Do not suggest future features unless they block the next step.
```

### One-Feature MVP

> Reduce an idea to the single feature that could be built in 1–2 days.

**When to use:** Before building a new app idea, when you want the smallest version that still proves the point.

#### Prompt
```text
Turn this into a one-feature MVP. Identify:
- the single core action
- the user's main pain
- the smallest useful interface
- what screens are unnecessary
- what can be done manually for v1
```

#### Variations
**Reduce to one strong feature:**
```text
Review this app idea and reduce it to one strong feature. Tell me:
- what the app is really about
- what the user does in the first 30 seconds
- what feature should be removed
- what feature should wait until v2
- what would make this feel focused and native
```

**Buildable in 1–2 days:**
```text
Find the smallest version of this that could be built in 1-2 days. Include:
- core feature
- needed screens
- data model
- what to fake manually
- what not to build
```

### One-Screen App Review

> Fit the main workflow on one clear screen — for small Mac utilities that shouldn't sprawl.

**When to use:** For small Mac utilities where you want most of the app to work from one clear screen.

#### Prompt
```text
Review this app as a one-screen utility.

Check:
- whether the main workflow can fit on one screen
- what panels are unnecessary
- what can move to Settings
- what can become a menu item
- what can be hidden until needed
- what the primary action should be
- what secondary actions should be less visible

Rules:
- reduce navigation
- avoid dashboard layout
- keep the main action obvious
- prefer compact native controls
- do not add onboarding unless necessary
```

### Prompt Improvement

> Fix a vague prompt so the model stops guessing.

**When to use:** A prompt gives bad output, causes guessing, or needs to be clearer before sending to Agent or another agent.

#### Prompt
```text
Review this prompt and identify:
- vague instructions
- missing context
- conflicting requirements
- places where the model may guess
- how to rewrite it more clearly
```

#### Variations
**Make it stronger:**
```text
Make this prompt stronger. Improve:
- goal
- constraints
- input format
- output format
- stop conditions
- examples
```

**Prompt-editor rewrite:**
```text
Act as a prompt editor. Rewrite this so an AI agent can follow it without guessing. Include:
- exact task
- context
- rules
- output format
- what not to do
```

### README / Project Docs

> Cut length and hype; make a README direct and useful for the next person.

**When to use:** A repo README feels too long, too vague, too marketing-heavy, or not useful for someone opening the project.

#### Prompt
```text
Review this README and identify:
- what is unclear
- what is too long
- what is missing for a new user
- what sounds fake or inflated
- how to make it more direct
```

#### Variations
**Rewrite for a serious open-source project:**
```text
Rewrite this README for a serious open-source project. Make it:
- clear
- specific
- not marketing-heavy
- easy to scan
- honest about what works and what does not
```

**Remove hype:**
```text
Review this project description and remove hype. Keep:
- what it does
- who it is for
- why it exists
- how to run it
- current limitations
```

### Safety Check Before Big Change

> Pressure-test a big change before building it — find the simpler alternative and the smallest safe version.

**When to use:** Before architecture changes, database changes, sync, cloud features, agents, MCP, permissions, or anything that may cause a rabbit hole.

#### Prompt
```text
Before making this big change, evaluate whether it is actually needed.

Identify:
- simpler alternatives
- risks
- hidden maintenance cost
- what can be manual for now
- what would prove this is needed
- the smallest safe implementation

Do not implement yet.
```

### Session Start Checklist

> Make the agent inspect the project and propose a short plan before it touches any code.

**When to use:** Before any Agent run, especially when returning to a project after a break or when you want Agent to plan before editing.

#### Prompt
```text
Before starting work, inspect the project and create a short session plan.

Include:
- current project state
- files likely involved
- first safe task
- risks
- what not to touch
- expected result for this session

Do not code yet. First explain the plan.
```

### Simplicity Review

> Strip over-engineering down to the smallest version that still solves the real problem.

**When to use:** A plan, feature list, or architecture feels too big, too abstract, or too "startup-y" for the real problem.

#### Prompt
```text
Review this and identify:
- over-engineering
- unnecessary abstraction
- fake scalability
- features that should be delayed
- the simplest version that still solves the real problem
```

#### Variations
**Cut vs. build-first:**
```text
Look at this plan and tell me:
- what is too complicated
- what exists only because it sounds impressive
- what can be removed without hurting the core value
- what I should build first
- what I should explicitly NOT build yet
```

**Strict product editor:**
```text
Act as a strict product editor. Cut this down to the smallest useful version. Separate:
- must-have
- nice later
- distraction
- risky complexity
- unclear value
```

### UI / Design Review

> Find the visual noise and make an interface calmer and more native.

**When to use:** Reviewing mockups, app screens, settings pages, dashboards, or any interface that feels too busy.

#### Prompt
```text
Review this UI concept and identify:
- visual noise
- unnecessary panels
- unclear hierarchy
- controls that should be hidden or delayed
- how to make it feel more Apple-native
```

#### Variations
**Apple HIG designer:**
```text
Act as an Apple HIG-focused designer. Review this interface for:
- spacing
- hierarchy
- native macOS feel
- unnecessary decoration
- confusing interactions
- what to simplify first
```

**Make it calmer:**
```text
Review this mockup and make it calmer. Identify:
- what is too loud
- what feels non-native
- what can be removed
- what should be moved to settings
- what the main action should be
```

### Workflow Simplifier

> Turn a personal routine into the smallest calm checklist that still works.

**When to use:** Designing a daily workflow, checklist, folder system, project ritual, or automation routine.

#### Prompt
```text
Review this workflow and identify:
- steps I do not need
- places where I am creating busywork
- where automation would actually help
- where automation would make things worse
- the simplest daily version
```

#### Variations
**For someone who gets distracted easily:**
```text
Simplify this workflow for someone who gets distracted easily. Identify:
- the minimum steps
- the best order
- what should be a checklist
- what should be automated
- what should be ignored
```

**Calm checklist:**
```text
Turn this workflow into a calm checklist. Keep it:
- short
- repeatable
- clear
- low-friction
- focused on finishing, not organizing
```

### Assumption Breaker

> When stuck: stop debugging, find the false belief instead.

**When to use:** You've been on the same problem long enough that the problem is probably not where you're looking.

#### Prompt
```text
I've been stuck on this for a while. Do not help me debug yet.

Instead:
- list every assumption I am implicitly making in this description
- rank them by likelihood of being false
- give me the single cheapest test to falsify the top one

Do not propose a fix until I report back.

Problem:
[paste]
```

### Premortem

> It's six months later and it failed. Write that postmortem now.

**When to use:** Before committing real time to a project — cheaper than learning the same thing later.

#### Prompt
```text
It is [timeframe] from now and this project failed completely.

Write the postmortem from that future:
- the 5 most likely causes, ranked by probability
- for each: the earliest signal I would have seen
- for each: the cheapest thing I could do this week to de-risk it

Do not reassure me. Assume failure and explain it.

Project:
[paste]
```

### Second-Order Effects

> And then what happens? Walk consequences three orders deep.

**When to use:** Before a decision that is hard to reverse — architecture, dependency, naming, public commitment.

#### Prompt
```text
I am considering: [decision]

Walk the consequences three orders deep:
- immediate effect
- what that causes
- what that causes

Flag any loop that reinforces itself.
End with the one second-order effect I am most likely blind to.
```

### Verify the Last Run

> Verify what the last run actually did — don't trust its summary.


#### Prompt
```text
Review the work completed in the last run.

Check:
- what was actually implemented
- what remains incomplete
- whether the implementation matches the original request
- whether any shortcuts changed the intended behavior
- new bugs, warnings, or regressions
- unrelated files that changed
- documentation that is now inaccurate

Do not trust the previous summary. Verify against the code and current app behavior.

End with:
- confirmed complete
- incomplete
- incorrect
- next safest step
```

### Compare the Task Against the Implementation

> Requirement-by-requirement gap report against the original task.


#### Prompt
```text
Read the original task and compare it directly with the current implementation.

For every requirement, mark it as:
- complete
- partially complete
- missing
- implemented differently
- no longer relevant

Identify:
- assumptions that were made without permission
- features that were added but not requested
- requirements that were silently skipped
- places where the implementation technically works but misses the intent

Do not make changes yet. Produce an honest implementation gap report.
```

### Find Regressions Before Continuing

> Hunt regressions before you let the agent continue.


#### Prompt
```text
Inspect the latest changes for regressions.

Check:
- existing features that may have stopped working
- broken navigation
- lost state or data
- layout issues at different window sizes
- keyboard shortcuts
- focus behavior
- loading and empty states
- error handling
- persistence
- performance changes

Prioritize issues that could cause data loss, crashes, or broken core workflows.

Do not add new features. Recommend the smallest safe fixes.
```

### Review Code Quality

> Practical code review — simplification over theoretical redesign.


#### Prompt
```text
Review this code and identify:
- unnecessary abstraction
- duplicated logic
- confusing naming
- hidden bugs
- places where a simpler implementation would be better

Be specific. Prefer practical simplifications over theoretical redesigns.
```

### Remove Accidental Complexity

> Find complexity the product requirements never asked for.


#### Prompt
```text
Review the current implementation and identify complexity that is not justified by the product requirements.

Look for:
- unnecessary protocols
- premature dependency injection
- excessive view models
- generic systems used only once
- wrappers around simple APIs
- deeply nested state
- too many files for a small feature
- configuration that could be static
- abstractions created for hypothetical future needs

For each issue, explain:
- why it is unnecessary
- what risk it creates
- the simpler alternative

Do not simplify code where the abstraction is already providing clear value.
```

### Find Duplicate Sources of Truth

> One owner per piece of state — find the competing copies.


#### Prompt
```text
Review the feature for duplicated state or competing sources of truth.

Check for:
- the same value stored in multiple objects
- UI state duplicated from model state
- cached values that can become stale
- settings represented in more than one place
- persistence and in-memory state drifting apart
- multiple services owning the same responsibility
- derived values stored instead of calculated

Recommend one clear owner for each piece of state.

Prefer the smallest refactor that prevents future inconsistencies.
```

### Check for Fake Scalability

> Scalability work for a scale that doesn't exist.


#### Prompt
```text
Review the architecture for scalability work that the product does not currently need.

Identify:
- systems designed for millions of records without evidence
- complex caching
- background queues
- distributed-style abstractions
- plugin architectures
- overly generic storage layers
- multi-user concepts in a solo-user app
- service boundaries with no practical benefit

Explain what real constraint each system solves.

Where no current constraint exists, recommend a simpler implementation.
```

### Review a Proposed Refactor

> Judge a refactor before you start it, not after.


#### Prompt
```text
Review this proposed refactor before implementing it.

Determine:
- what concrete problem it solves
- whether the current code is actually causing trouble
- whether the refactor reduces or increases complexity
- how many files and concepts it affects
- what could regress
- whether a smaller local cleanup would be sufficient
- whether the refactor should happen now or later

Do not approve a refactor based only on theoretical cleanliness.
```

### Review Performance Without Premature Optimization

> Real performance problems, separated from hypothetical ones.


#### Prompt
```text
Inspect the current implementation for real performance problems.

Check:
- repeated expensive work
- unnecessary file scans
- excessive view updates
- blocking the main thread
- large data loaded eagerly
- repeated parsing
- avoidable model calls
- unbounded history or caches
- work triggered on every keystroke
- slow startup behavior

Separate measured or clearly likely issues from hypothetical concerns.

Recommend simple fixes before introducing caches or architectural changes.
```

### Choose the Next Safest Task

> One next task — the safest one.


#### Prompt
```text
Review the current project state and recommend the next development task.

Consider:
- incomplete core functionality
- regressions
- data safety
- blockers
- testability
- dependencies between tasks
- risk of expanding scope
- value to the user

Recommend one primary next task only.

Explain:
- why it should be next
- what should not be touched
- how success should be verified
- what can safely wait
```

### Find Features That Should Be Delayed

> Find what should be delayed, not built.


#### Prompt
```text
Review the current task and identify work that should not be included in the first version.

Look for:
- speculative flexibility
- integrations without a proven workflow
- advanced customization
- collaboration features for a solo app
- analytics
- plugin systems
- automation before the manual workflow is stable
- complex import and export formats
- edge-case UI that expands the scope significantly

Separate:
- required for the core workflow
- useful soon
- safe to delay
- should probably be removed

Protect a focused, shippable first version.
```

### Review the UI Against the Product Intent

> Does the UI serve the product intent, or just the mockup?


#### Prompt
```text
Review the current UI implementation against the intended product experience.

Focus on:
- whether the main task is immediately clear
- visual hierarchy
- unnecessary controls
- spacing consistency
- native macOS behavior
- keyboard accessibility
- discoverability
- empty states
- whether secondary actions distract from the main action
- whether the interface feels calm or crowded

Do not suggest a redesign unless the current structure prevents the intended workflow.

Recommend small, practical improvements first.
```

---

## Build & Ship

### Asset Integration Check

> Review how icons and images are named, placed, and referenced — and flag the unused or broken ones.

**When to use:** When adding icons, screenshots, product images, app mockups, or other assets into a project.

#### Prompt
```text
Review the app assets and image usage.

Check:
- correct file names
- correct asset catalog placement
- image sizes
- light/dark variants if needed
- missing @2x/@3x assets if relevant
- unused assets
- blurry or stretched images
- licensing/source notes if relevant
- whether assets are referenced correctly in code

Rules:
- do not resize or edit original assets unless requested
- do not replace visual style
- keep asset names clear
- remove only confirmed unused assets
```

### Build & Run Verification

> Confirm the project actually builds and runs — and separate confirmed results from assumptions.

**When to use:** After Agent changes files, especially before trusting that a task is done.

#### Prompt
```text
Verify that the project builds and runs as expected.

Check:
- correct build command
- compile errors
- missing files
- broken imports
- warnings that matter
- runtime assumptions
- basic smoke test path
- docs that mention wrong commands

Rules:
- do not claim success unless the command confirms it
- if you cannot run the app, explain exactly why
- separate confirmed results from assumptions
- suggest the smallest fix for any build issue
```

### Dark & Light Mode Polish

> Fix the colors, contrast, and states that look wrong when the app switches appearance.

**When to use:** When the app works in one appearance but looks wrong in the other.

#### Prompt
```text
Review and improve light mode and dark mode support.

Check:
- hardcoded colors
- low contrast text
- backgrounds that do not adapt
- borders and separators
- selected states
- hover states
- disabled states
- icons and SF Symbols
- settings window appearance

Rules:
- use system colors where possible
- avoid custom color systems unless needed
- do not change the app layout
- keep the design calm and native
- summarize what still needs visual testing
```

### Keyboard-First Review

> Make the app fast from the keyboard — shortcuts, focus, and tab order, without overdoing it.

**When to use:** When you want the app to feel faster and more native, especially for menu bar tools, launchers, checklists, or utility apps.

#### Prompt
```text
Review this app for keyboard-first usage.

Check:
- obvious keyboard shortcuts
- default focused control
- tab order
- escape behavior
- return/enter behavior
- command shortcuts
- search field focus
- menu commands
- accessibility labels
- mouse-only interactions that should have keyboard alternatives

Rules:
- do not add too many shortcuts
- prefer standard macOS shortcuts
- keep shortcuts discoverable in menus where relevant
- do not change the core workflow
```

### Menu Bar App Review

> Keep a menu bar utility lightweight, obvious, and out of dashboard territory.

**When to use:** For menu bar apps, small utilities, checklists, status tools, or always-available Mac helpers.

#### Prompt
```text
Review this as a macOS menu bar app.

Check:
- menu bar icon behavior
- popover size
- launch at login need
- main window vs popover split
- quick actions
- settings access
- empty state
- keyboard behavior
- whether it should stay out of the Dock
- what should happen when clicking outside

Rules:
- keep it lightweight
- avoid full dashboard behavior
- make the first action obvious
- prefer system patterns
- do not add features unrelated to the menu bar use case
```

### Native macOS Check

> Make a SwiftUI/AppKit app feel like a real Mac app instead of a web app in a window.

**When to use:** For SwiftUI/AppKit apps when you want the app to feel more like a real Mac app instead of a web app inside a window.

#### Prompt
```text
Review this app for native macOS quality.

Check:
- menu behavior
- keyboard shortcuts
- window behavior
- toolbar/sidebar usage
- settings placement
- empty states
- system controls
- SF Symbols usage
- HIG alignment

Suggest practical improvements without overcomplicating the app.
```

### No-New-Features Polish

> Make the app feel better with a hard no-new-features rule — fix rough edges, expand nothing.

**When to use:** When the app needs to feel better but you do not want Agent to expand scope.

#### Prompt
```text
Do a polish pass with a strict no-new-features rule.

Allowed:
- fix spacing
- fix naming
- fix obvious UI rough edges
- improve empty states
- improve error messages
- remove clutter
- simplify labels
- update docs if needed

Not allowed:
- new major screens
- new data models
- new services
- new providers
- new settings unless essential
- architecture changes
- speculative future features

At the end, list what changed and confirm that no new feature scope was added.
```

### Polish UI Without Changing Behavior

> Visual cleanup only — spacing, alignment, hierarchy, native feel — with the flow left intact.

**When to use:** When the app basically works but the interface needs visual cleanup, calmer spacing, or better native feel.

#### Prompt
```text
Polish the UI without changing app behavior.

Focus on:
- spacing
- alignment
- hierarchy
- native macOS feel
- simpler labels
- calmer layout

Rules:
- do not add features
- do not change data models
- do not rewrite logic
- keep the current flow intact
```

### Release Readiness

> Sort a v1 into blockers, important polish, and safe-to-delay before you ship it.

**When to use:** Before calling something v1, sharing it, zipping it, sending it to someone, or moving to the next project.

#### Prompt
```text
Review this app for v1 release readiness.

Check:
- launch flow
- obvious bugs
- empty states
- error states
- onboarding or first-use clarity
- settings
- docs
- build/run instructions
- what must be fixed before release
- what can wait

Return:
- blockers
- important polish
- safe to delay
- final next steps
```

### Resizable Layout + Settings

> Make the app behave at every window size and clean up Settings — without redesigning it.

**When to use:** When the app looks good at one window size but breaks, feels cramped, or doesn't adapt when resized. Also when settings are messy, too visible, or not clearly separated from the main workflow.

#### Prompt
```text
Review and improve this app so it works well at different window sizes.

Focus on:
- resizable window behavior
- minimum window size
- flexible layouts
- adaptive spacing
- sidebar/content resizing
- scroll behavior
- empty states at small sizes
- large-window layout that does not feel stretched
- avoiding clipped text or controls
- keeping the main action visible

Also review Settings:
- what belongs in Settings
- what should stay in the main UI
- what settings are unnecessary for v1
- how settings should be grouped
- what defaults should be used
- what advanced options should be hidden or delayed

Rules:
- do not redesign the whole app
- do not add new features
- keep the current app purpose intact
- prefer native macOS patterns
- use system controls where possible
- keep the layout calm and simple
- make resizing feel intentional, not accidental

Before coding, explain:
- what layout issues you found
- what settings issues you found
- the smallest safe changes to make

After coding, summarize:
- what changed
- which files changed
- what sizes were considered
- what still needs manual visual testing
```

#### Variations
**Shorter version:**
```text
Make this app resize properly and clean up Settings.

Check:
- small window behavior
- large window behavior
- minimum size
- flexible spacing
- scroll areas
- clipped text
- sidebar/content resizing
- what belongs in Settings vs main UI

Do not redesign the app.
Do not add features.
Keep the current flow intact.
Use native macOS patterns.

First explain the layout/settings plan, then make the smallest safe changes.
```

### Screenshot to Implementation

> Implement the closest practical version of a mockup's look — without copying complexity or adding features.

**When to use:** When you have a screenshot or mock image and want Agent to implement the look without overbuilding.

#### Prompt
```text
Use this screenshot/mockup as visual reference and implement the closest practical version in the current app.

Focus on:
- layout structure
- spacing
- hierarchy
- native controls
- typography feel
- main action placement
- calm visual style

Rules:
- do not copy decorative details that add complexity
- do not add features that are only visible in the mockup
- do not change app architecture
- keep the implementation native and maintainable
- explain what you matched and what you intentionally simplified
```

### Settings Architecture Review

> Keep settings small and native — prefer good defaults, hide the advanced, cut the rest for v1.

**When to use:** When settings are growing too fast or becoming mixed with the main app logic.

#### Prompt
```text
Review the settings architecture for this app.

Identify:
- settings that are actually needed
- settings that should be defaults, not options
- settings that should move to Advanced
- settings that should be removed for v1
- how settings should be grouped
- where settings should be stored
- whether settings need migration or reset behavior

Rules:
- avoid adding preferences for every small behavior
- prefer good defaults
- keep settings native to macOS
- separate settings UI from app logic where useful
- keep the settings window simple
```

### Visual QA Checklist

> Turn UI changes into a concrete checklist of what to eyeball before release.

**When to use:** After UI changes, especially in SwiftUI/macOS apps where the app compiles but the layout may feel wrong.

#### Prompt
```text
Review the UI visually and create a QA checklist.

Check:
- spacing
- alignment
- clipped text
- empty states
- small window size
- large window size
- dark mode
- light mode
- sidebar behavior
- keyboard navigation
- settings window
- buttons and labels
- disabled/loading/error states

Return:
- issues found
- likely files involved
- fixes needed before release
- polish that can wait
```

### Zip & Handoff Readiness

> Get a project ready to zip and hand off — current docs, no secrets, no build junk.

**When to use:** Before creating a zip to share, archive, or continue on another machine.

#### Prompt
```text
Prepare this project for zipping and handoff.

Check:
- README is current
- HANDOFF.md is current
- TODO.md is current
- build/run instructions exist
- unnecessary build artifacts are excluded
- secrets or API keys are not included
- large generated files are not included
- sample config is included if needed
- next steps are clear

Rules:
- do not include private data
- do not include derived build folders
- do not invent missing setup steps
- make the zip useful for the next session
```

### Dependency Justifier

> Should this be a dependency or twenty lines of my own code?

**When to use:** Any time you're about to install something to solve a problem you haven't tried solving yourself.

#### Prompt
```text
I am about to add [package] to this project.

Tell me:
- what it actually does, minus the marketing
- transitive dependency count and install size
- last publish date and bus factor
- the ~20-line version I could write instead
- verdict: add or inline

Be decisive. Do not give me a balanced view.
```

### Revert or Forward-Fix

> Decide in sixty seconds, under pressure, with the commands ready.

**When to use:** Something shipped and broke. You need a decision, not a discussion.

#### Prompt
```text
Something is broken after a deploy.

Change: [what shipped]
Symptom: [what's wrong]
Time since deploy: [how long]

Give me, in this order:
1. revert or forward-fix — one line, no hedging
2. the reasoning in 3 bullets
3. the exact commands

Bias toward revert unless the revert itself is dangerous. If it is, say so first.
```

### Final Pre-Commit Review

> Last look at the diff before it becomes a commit.


#### Prompt
```text
Perform a final review of the current uncommitted changes.

Check:
- the diff matches the task
- no unrelated files changed
- no secrets or personal paths were added
- debug code is removed
- naming is clear
- errors are handled
- documentation is accurate
- build warnings were not introduced
- destructive actions are safe
- the feature can be tested manually

Do not modify files unless a clear issue is found.

End with one result:
- ready to commit
- ready after small fixes
- not ready to commit
```

### Final Pre-Release Review

> Release-candidate pass: blockers vs nice-to-have.


#### Prompt
```text
Review the app as a release candidate.

Check:
- core workflows
- app launch and relaunch
- persistence
- permissions
- offline behavior
- error recovery
- empty states
- window resizing
- keyboard navigation
- accessibility
- upgrade or migration behavior
- release documentation
- known limitations

Separate:
- release blockers
- important but non-blocking issues
- safe post-release improvements

Be conservative. Do not treat visual polish issues as release blockers unless they prevent use.
```

### Clean Up After the Feature

> Focused cleanup after the feature works — no redesign.


#### Prompt
```text
Now that the feature is working, perform a focused cleanup pass.

Check:
- dead code
- temporary debug output
- unused files
- obsolete comments
- duplicate helpers
- abandoned feature flags
- placeholder UI
- unnecessary imports
- stale TODOs
- old documentation

Do not redesign or restructure working code.

Only remove items that are clearly unused or made obsolete by this feature.
```

### Review Concurrency and Async Code

> Async ownership, cancellation, races, stale responses.


#### Prompt
```text
Review all asynchronous and concurrent code in this change.

Check:
- tasks that outlive their views
- cancellation
- duplicate requests
- updates on the wrong actor
- race conditions
- stale responses replacing newer results
- progress state
- error propagation
- retained objects
- unnecessary background work

Prefer structured concurrency and clear ownership.

Do not add concurrency where synchronous work is already fast and safe.
```

### Implement Only the Requested Change

> Implement exactly what was asked. Nothing else.


#### Prompt
```text
Implement the requested change and nothing beyond it.

Before editing:
- identify the smallest set of files that should change
- note any existing behavior that must remain unchanged
- identify likely regression risks

During implementation:
- preserve the current architecture
- reuse existing components where appropriate
- avoid introducing a general system for a single use case
- do not rename unrelated code
- do not perform opportunistic cleanup

After implementation:
- list files changed
- explain the behavior added
- verify the original request
- report anything that remains unresolved
```

### Fix the Bug Without Expanding Scope

> Smallest reliable fix, root cause named, scope held.


#### Prompt
```text
Investigate and fix the reported bug.

First:
- reproduce or trace the failure
- identify the actual root cause
- separate the root cause from visible symptoms
- check whether the bug affects other areas

Then:
- apply the smallest reliable fix
- avoid unrelated refactors
- preserve existing behavior
- add or update a focused test where practical

End with:
- root cause
- fix made
- regression risk
- verification performed
```

### Validate the Feature Manually

> A manual test checklist with observable steps.


#### Prompt
```text
Create a manual test checklist for this feature.

Include:
- normal workflow
- first-run workflow
- empty state
- invalid input
- cancelled action
- repeated action
- app relaunch
- small and large windows
- keyboard-only use
- failure recovery
- persistence verification
- interaction with existing features

Make each test concrete and observable.

Do not use vague steps such as “make sure it works.”
```

### Review Feature Flags

> Audit feature flags — and remove the finished ones.


#### Prompt
```text
Review all feature flags and experimental toggles.

For each flag, determine:
- who uses it
- whether it is still needed
- default state
- failure risk
- removal plan
- documentation
- interaction with persisted data

Remove flags for completed or abandoned experiments.

Do not use feature flags to avoid finishing incomplete product decisions.
```

### Review Debug UI

> Find debug UI that shouldn't ship.


#### Prompt
```text
Review the app for debug-only controls or information.

Look for:
- debug buttons
- raw identifiers
- test data
- developer menus
- placeholder labels
- temporary status text
- manual refresh buttons
- internal provider names
- verbose logs
- hidden shortcuts

Remove or isolate debug tools from production builds.

Keep diagnostics available through an intentional developer or troubleshooting path.
```

---

## Design & UI

### Accessibility & WCAG Review

> Audit and fix accessibility so every interactive element and piece of content meets WCAG.

**When to use:** Before shipping, or when accessibility hasn't been checked yet.

#### Prompt
```text
Review and improve the application's accessibility, ensuring WCAG compliance for all interactive elements and content.
```

### Analyze & Improve the App

> A prioritized pass over UI, UX, performance, and usability — then ship the highest-impact fixes.

**When to use:** A broad "make this better" pass when you're not sure where to start.

#### Prompt
```text
Analyze this app and suggest improvements for UI, UX, performance, and usability.
Implement the most impactful changes.
```

### Global Hotkey Command Palette

> Add a global-hotkey command palette to a SwiftUI macOS app for fast search and actions.

**When to use:** Building a keyboard-first macOS app that needs an instant, from-anywhere launcher.

#### Prompt
```text
Implement a global hotkey (e.g., Option+Space) that brings up the command palette in the SwiftUI macOS app. The command palette should allow users to quickly search for snippets, create new ones, and trigger various app actions.
```

### Liquid Glass Material

> Apply Apple's Liquid Glass material to a SwiftUI macOS window and sidebar — subtle, readable.

**When to use:** Modernizing a macOS app's chrome to match Apple's latest material design.

#### Prompt
```text
Apply the Liquid Glass material to the main window background and sidebar of the SwiftUI macOS app. Ensure the material effect is subtle and enhances the readability of content while adhering to Apple's latest design guidelines.
```

### macOS App Icon (HIG)

> Brief a macOS app icon that sits comfortably next to Apple's own — clean silhouette, subtle depth, HIG-correct.

**When to use:** Designing or regenerating an app icon that should feel native in the Dock and Finder.

#### Prompt
```text
Design a macOS-style icon that adheres to Apple's Human Interface Guidelines (HIG) for a rounded app tile. The icon should have a clean silhouette, controlled materials, subtle depth, and balanced proportions. It should feel polished and refined, not loud or toy-like. The color palette and lighting should be suitable for placement alongside Apple apps in the Dock and Finder.
```

#### Variations
**A few options, legible at small sizes:**
```text
Design a few icon options for my macOS desktop app. Follow HIG — a standard macOS-style rounded app tile:
- clean silhouette
- controlled materials
- subtle depth
- balanced proportions
- deference

The icon should feel polished, not loud or toy-like. The palette and lighting should feel at home beside Apple apps in the Dock and Finder. Keep it clear, simple, recognizable at small sizes, native to macOS, and layered with subtle depth — not excess decoration.
```

### Raycast-Quality UI Refactor

> Tighten a UI to Raycast-level polish — minimal, compact, keyboard-first.

**When to use:** When a tool or command UI should feel fast, dense, and keyboard-driven.

#### Prompt
```text
Refactor this UI to match Raycast-level design quality.
Use:
- minimal layout
- tight spacing
- keyboard-first interactions
- compact lists
- subtle separators
```

### Reduce Cognitive Load

> Calm a busy UI — clearer state, fewer competing actions, an obvious primary path.

**When to use:** A screen feels overwhelming or users hesitate about what to do next.

#### Prompt
```text
Reduce cognitive load by simplifying state visibility, minimizing competing actions, and clarifying primary workflows.
```

### Refactor UI to Apple HIG

> Bring a UI in line with Apple's Human Interface Guidelines — clean spacing, SF Symbols, native components.

**When to use:** Polishing a macOS or iOS view so it feels native and refined rather than generic.

#### Prompt
```text
Refactor this UI to follow Apple Human Interface Guidelines.
Use clean spacing, proper padding, SF Symbols, and native SwiftUI components.
```

### Refine Animations

> Smooth and polish interaction animations so they feel refined, not distracting.

**When to use:** When animations already exist but feel janky or unpolished.

#### Prompt
```text
Refine the existing animations for task completion and subtask interactions, ensuring they are even smoother and more visually appealing.
```

### Remove Unnecessary Steps

> Cut steps out of an interface so people finish tasks faster.

**When to use:** A flow feels heavier than it should — too many clicks or screens between intent and result.

#### Prompt
```text
Analyze this interface and remove unnecessary steps.
Simplify the workflow so users complete tasks faster.
```

### Responsive Layout

> Make a layout adapt cleanly across screen sizes without losing usability.

**When to use:** A web or cross-device UI that needs to work from phone to desktop.

#### Prompt
```text
Implement responsive design principles for the app's layout. The layout should automatically adjust to fit various screen sizes, ensuring a consistent and user-friendly experience across different devices — adjusting the size and position of UI elements (buttons, text fields, navigation menus) to maintain usability and aesthetics.
```

#### Variations
**With CSS media queries:**
```text
Implement responsive design principles for the app's layout. The layout should automatically adjust to fit various screen sizes, from small mobile phones to large desktop monitors. Use CSS media queries to achieve this.
```

**Mobile & desktop, scale images:**
```text
Make the app's layout responsive so it adapts to different screen sizes. Ensure images are scaled appropriately and text remains readable on both mobile and desktop views.
```

### Slim Status Bar

> A minimal bottom status bar showing model, tools, cost, and connection — AI control-room style.

**When to use:** Giving an AI app an at-a-glance footer without cluttering the main view.

#### Prompt
```text
Design and implement a slim status bar for the bottom UI. This status bar should display key information at a glance: the current AI model being used, any active tools, estimated API cost, and the connection status. The design must be minimal, flat, and unobtrusive, fitting seamlessly with the macOS AI control room aesthetic and the overall use of whitespace and thin dividers.
```

### Smooth Scrolling & Micro-interactions

> Add non-intrusive scroll and micro-interaction polish that complements a minimalist layout.

**When to use:** A page feels static and you want tasteful motion without breaking the calm.

#### Prompt
```text
Incorporate smooth scrolling and subtle micro-interactions into the homepage layout. Focus on animations that enhance the modern typography and responsive design, ensuring they are non-intrusive and complement the minimalist visual style and original color palette.
```

### Solo-App Simplicity (One Layer Deeper)

> Keep a build scoped for a solo macOS app — minimal complexity, readable, fast to iterate.

**When to use:** As a constraint on any build request so it doesn't grow past what one person can maintain.

#### Prompt
```text
Follow the "one layer deeper" rule.
Build this for a solo macOS app with minimal complexity.
Optimize for readability and iteration speed.
```

### Impossible States

> Kill the boolean soup — make bad states unrepresentable.

**When to use:** When a view has three or more independent booleans and you've already hit a combination that shouldn't exist.

#### Prompt
```text
This code uses boolean flags for state.

Convert it to a discriminated union / enum with associated values so impossible states cannot be represented.

Show me:
- the type
- the valid transitions
- which specific bugs this eliminates
- what the view code looks like after

Code:
[paste]
```

### Match a Mockup Without Overbuilding

> Match the mockup without inventing extra product.


#### Prompt
```text
Use the provided screenshot or mockup as a visual direction for the current screen.

Match:
- overall layout
- panel proportions
- alignment
- spacing rhythm
- typography hierarchy
- control placement
- visual density
- native material usage

Do not copy:
- decorative elements with no function
- fake data-heavy sections
- unsupported interactions
- platform-inappropriate controls
- features that are not part of the task

Keep the existing architecture unless a small local change is required.

After implementation, explain:
- what was matched
- what was adapted for native macOS behavior
- what was intentionally omitted
```

### Simplify the Current Screen

> Cut this screen down to what it's for.


#### Prompt
```text
Review this screen and identify everything that can be removed, merged, hidden, or delayed.

Classify each element as:
- essential now
- useful but secondary
- should move to a menu or inspector
- should live in settings
- future feature
- unnecessary

Protect the primary workflow.

Do not remove controls that are required for safety, navigation, or understanding the current state.
```

### Refactor Toward a Raycast-Style Interface

> Refactor toward a Raycast-style interface.


#### Prompt
```text
Review the current interface and refactor it toward a compact Raycast-style structure.

Focus on:
- fast keyboard-first navigation
- compact rows
- clear selection
- one primary content area
- predictable action placement
- minimal persistent controls
- strong information hierarchy
- low visual noise

Prefer:
- sidebar or list on the left
- selected content or details on the right
- actions in a command menu
- contextual metadata instead of large toolbars
- concise labels
- native macOS controls

Avoid:
- dashboard cards
- oversized headers
- unnecessary tabs
- duplicated actions
- floating buttons
- decorative containers
- custom interactions where standard macOS behavior is sufficient

Do not copy Raycast visually line by line.

Preserve the product’s identity and existing architecture.

After refactoring, explain:
- what became faster
- what was removed
- what moved into commands
- what remains intentionally different from Raycast
```

### Raycast-Style Refactoring Without a Redesign

> Raycast feel without a full redesign.


#### Prompt
```text
Refactor this screen using Raycast-style interaction principles without redesigning the product.

Check:
- whether the main action is available from the keyboard
- whether secondary actions can move into a command menu
- whether rows can become more compact
- whether selection is visually obvious
- whether unnecessary panels can be removed
- whether metadata can be shown more quietly
- whether the user can complete the workflow without reaching for the mouse

Do not:
- change the data model
- replace the navigation architecture
- add a universal launcher unless required
- turn every feature into a command
- introduce custom visual effects

Make the smallest structural improvements that create a faster, calmer interface.
```

### Build a Raycast-Style Action Panel

> A contextual action panel, Raycast-style.


#### Prompt
```text
Implement a contextual action panel for the selected item.

Requirements:
- actions reflect the current selection
- unavailable actions are disabled or omitted appropriately
- primary actions appear first
- destructive actions appear last
- keyboard shortcuts are displayed
- action names use verbs
- the panel is fully keyboard navigable
- Escape closes the panel
- Return performs the selected action
- selection returns to the previous interface after closing

Do not duplicate every toolbar or context-menu action.

Use one action model as the source of truth where practical.
```

### Compact the Interface

> Tighten density without shrinking usability.


#### Prompt
```text
Review the current screen and reduce unnecessary visual space.

Check:
- row height
- toolbar height
- header height
- panel padding
- section spacing
- card padding
- icon size
- control spacing
- empty decorative areas
- repeated labels
- oversized buttons

The goal is not maximum density.

The goal is:
- faster scanning
- more useful content visible
- clear selection
- calm spacing
- less mouse travel

Do not reduce hit targets below comfortable native sizes.
```

### Remove Dashboard Styling

> Strip dashboard styling out of a utility app.


#### Prompt
```text
Review the interface for dashboard-like styling that does not support the main workflow.

Look for:
- large cards
- statistics panels
- oversized welcome sections
- decorative summaries
- duplicated status information
- multiple competing sections
- large empty-state illustrations
- excessive rounded containers
- metrics without a clear action

Replace them with:
- compact lists
- quiet metadata
- native sidebars
- simple sections
- contextual details
- one clear next action

Do not remove information that is required for decision-making.
```

### Review Typography Like a Native Utility

> Typography for a native utility, not a website.


#### Prompt
```text
Review typography throughout the app.

Check:
- title hierarchy
- body text
- metadata
- labels
- monospaced content
- row density
- truncation
- line height
- text scaling
- contrast
- system font usage

Prefer:
- system fonts
- semantic text styles
- limited hierarchy levels
- quieter metadata
- stronger selected-item identity
- monospaced text only for code, paths, identifiers, or logs

Avoid oversized marketing-style typography inside a productivity app.
```

### Review Spacing System

> A spacing system, not ad-hoc padding.


#### Prompt
```text
Audit spacing throughout the interface.

Check:
- repeated horizontal padding
- repeated vertical spacing
- inconsistent section gaps
- toolbar alignment
- sidebar indentation
- row height
- inspector padding
- form spacing
- divider placement
- empty-state spacing

Create a small spacing system and reuse it.

Do not create dozens of spacing constants.

Prefer a few predictable values that support compact, regular, and spacious contexts.
```

### Review Visual Hierarchy Without Adding Decoration

> Hierarchy through structure, not decoration.


#### Prompt
```text
Improve visual hierarchy using:
- spacing
- alignment
- typography
- grouping
- dividers
- selection
- contrast

Do not rely on:
- gradients
- glow
- excessive shadows
- large cards
- multiple background colors
- decorative icons
- oversized headers

Make the primary task obvious without adding visual noise.
```

### Review Calm Visual Style

> Calm by default — no unnecessary visual noise.


#### Prompt
```text
Review the screen for unnecessary visual intensity.

Reduce:
- high-contrast borders
- excessive accent color
- repeated colored badges
- bright backgrounds
- too many materials
- unnecessary hover effects
- animated decoration
- competing selected states

Preserve:
- clear focus
- readable text
- visible selection
- accessible contrast
- important warnings
- destructive action distinction

Aim for a calm utility interface, not a promotional dashboard.
```

### Review Color Usage

> Color that carries meaning, semantically.


#### Prompt
```text
Audit all color use in the interface.

Classify color as:
- accent
- selection
- status
- warning
- destructive
- decorative
- unnecessary

Use color sparingly.

Ensure:
- status is not communicated by color alone
- accent color is not used on every control
- selection remains clear
- dark and light modes work
- disabled states remain readable
- custom colors adapt appropriately

Reduce the total number of colors where possible.
```

### Review Dark and Light Mode

> Review both appearances properly — no mechanical inversion.


#### Prompt
```text
Review the interface in both dark and light appearances.

Check:
- text contrast
- separator visibility
- material behavior
- selected rows
- hover states
- custom backgrounds
- icons
- images
- code blocks
- badges
- error states
- disabled controls

Do not invert colors mechanically.

Use semantic system colors wherever practical.
```

### Review SF Symbol Usage

> SF Symbols used correctly and consistently.


#### Prompt
```text
Audit all SF Symbols in the interface.

Check:
- whether the symbol meaning is clear
- whether the same action uses the same symbol everywhere
- whether filled and unfilled variants are used consistently
- whether symbols are decorative rather than informative
- whether text labels are needed
- symbol size and alignment
- accessibility labels
- rendering mode
- platform availability

Use symbols to support recognition, not replace unclear language.

Do not mix custom icon styles without a strong reason.
```

### Review the App for Power Users

> Review for power users — speed, not hand-holding.


#### Prompt
```text
Review the app specifically for frequent, experienced users.

Check:
- speed of repeated actions
- keyboard coverage
- command discoverability
- batch actions
- selection behavior
- reusable defaults
- recent items
- copy and paste workflows
- file and Finder integration
- focus restoration
- avoidable confirmation dialogs
- action consistency

Do not make the interface harder for new users solely to optimize expert workflows.

Use progressive disclosure so power features remain available without dominating the UI.
```

### Review the App for New Users

> Review the first-time experience without adding tutorials.


#### Prompt
```text
Review the same interface for first-time users.

Check:
- whether the app’s purpose is obvious
- whether the first action is clear
- whether icons require guessing
- whether terminology is understandable
- whether empty states guide action
- whether hidden commands have visible alternatives
- whether errors explain recovery
- whether advanced controls are shown too early

Do not add long onboarding.

Make the normal interface understandable without requiring documentation.
```

### Balance Beginner and Power-User Workflows

> One product that gets faster as you learn it.


#### Prompt
```text
Review how the interface supports both new and experienced users.

Provide:
- visible primary actions for beginners
- shortcuts for frequent actions
- command-palette access
- context menus
- progressive disclosure
- sensible defaults
- advanced settings only where needed

Avoid:
- hiding every action behind shortcuts
- showing every action permanently
- separate beginner and expert modes
- duplicated interfaces
- excessive tutorials

Use one consistent product that becomes faster as users learn it.
```

### Review a Utility App for One-Screen Use

> Can the core workflow live on one screen?


#### Prompt
```text
Review whether the core workflow can fit into one main screen.

Check:
- whether navigation is necessary
- whether separate tabs can become contextual panels
- whether the inspector can hold secondary details
- whether actions can move into menus
- whether settings are mixed into the workflow
- whether users lose context when navigating
- whether the main task remains visible

Do not force everything onto one screen if it creates crowding.

Aim for one stable workspace with optional secondary panels.
```

### Review Developer Tool Density

> Technical depth available without showing everything at once.


#### Prompt
```text
Review this developer-facing interface for excessive density or technical noise.

Separate:
- primary workflow information
- useful context
- diagnostics
- raw logs
- advanced controls
- provider details
- debug-only data

Keep technical depth available without showing everything simultaneously.

Move advanced details into:
- inspector
- disclosure sections
- command menu
- diagnostics window
- settings

Do not simplify away information required to understand destructive or automated actions.
```

---

## Platform & Infra

### AGENTS.md Improvement

> Make AGENTS.md hold only the repo-specific rules an agent actually needs — no generic advice.

**When to use:** When preparing a repo for Agent or another agent, especially if the agent keeps making the same mistakes.

#### Prompt
```text
Review and improve AGENTS.md for this project.

Include:
- project purpose
- tech stack
- important commands
- folder conventions
- coding style rules
- what files not to touch
- what to check before editing
- how to report completed steps
- common mistakes to avoid

Rules:
- keep it practical
- do not write generic agent advice
- include only rules that matter for this repo
- make it easy for Agent to follow
- prefer short bullet points
```

### App Icon Brief

> A concise Apple HIG-style brief for an app or menu bar icon — recognizable, no neon, no busy detail.

**When to use:** Before generating or designing an app icon, menu bar icon, or asset set.

#### Prompt
```text
Create a concise Apple HIG-style icon brief for this app.

Include:
- app purpose
- core symbol/metaphor
- shape idea
- light mode behavior
- dark mode behavior
- menu bar icon idea if needed
- what to avoid
- how it should feel in the Dock or menu bar

Rules:
- no emojis
- prefer SF Symbols logic where appropriate
- avoid glow/neon
- avoid busy details
- keep it recognizable at small sizes
```

### AppKit SwiftUI Boundary

> Keep AppKit only where it solves a real macOS need — and cut the wrappers that just fight the framework.

**When to use:** When a macOS app mixes SwiftUI and AppKit, or when Agent starts wrapping everything in unnecessary bridges.

#### Prompt
```text
Review the AppKit and SwiftUI boundaries in this project.

Identify:
- where SwiftUI is enough
- where AppKit is actually justified
- unnecessary wrappers or representables
- places where native macOS behavior is broken
- code that exists only to fight the framework
- the simplest boundary between SwiftUI and AppKit

Rules:
- do not replace working code unnecessarily
- keep AppKit only where it solves a real macOS need
- prefer native system behavior
- avoid custom controls unless clearly needed
```

### Daily Report

> Turn a messy work session into a concise, factual daily report that's useful tomorrow.

**When to use:** At the end of a work session, or when turning messy activity into a clean daily report.

#### Prompt
```text
Turn this work session into a concise daily report.

Include:
- what I worked on
- what changed
- decisions made
- blockers
- unfinished tasks
- next 3 actions
- links/files that matter

Rules:
- be factual
- do not over-explain
- separate completed from unfinished
- keep it useful for tomorrow
- avoid motivational language
```

### Folder Structure Review

> Find the smallest safe folder cleanup — without reorganizing everything or adding folders.

**When to use:** When a repo or app folder starts feeling messy, or before asking Agent to reorganize files.

#### Prompt
```text
Review the project folder structure.

Identify:
- files in the wrong place
- folders that are too broad
- folders that are unnecessary
- names that are confusing
- generated files that should be ignored
- docs that should move
- what should stay exactly where it is

Rules:
- do not reorganize everything
- avoid creating too many folders
- keep the structure easy for Agent to understand
- suggest the smallest safe cleanup
- list proposed moves before making them
```

### Local-First Review

> Decide what can stay local and pick the minimum reliable persistence model — no cloud unless required.

**When to use:** When deciding whether an app needs cloud, sync, auth, server storage, or can stay local.

#### Prompt
```text
Review this app from a local-first perspective.

Identify:
- what should stay local
- what data needs to persist
- what can be stored as files
- what needs SQLite or a local database
- what does not need cloud yet
- what does not need accounts/auth
- what backup/export option is enough for v1

Rules:
- do not add sync unless clearly required
- do not add a backend for v1 unless unavoidable
- prefer files, folders, SQLite, or local app storage
- keep privacy and portability simple
- suggest the minimum reliable persistence model
```

### MCP & Tools Workflow

> Give tools the least freedom that works — read-only first, explicit I/O, stop conditions on risk.

**When to use:** When adding MCP, external tools, plugins, or tool-calling flows to an app or agent.

#### Prompt
```text
Review this MCP/tools workflow.

Identify:
- what tool actions are actually needed
- where user confirmation is required
- what should be read-only
- what can modify files or data
- failure cases
- permissions risks
- logging/debug needs
- what should be delayed

Rules:
- do not give tools unlimited freedom
- make tool inputs and outputs explicit
- prefer read-only first
- separate tool discovery from tool execution
- add stop conditions for risky actions
```

### Provider & Model Settings

> Keep provider/model setup simple and secret-safe — and local-first where you can.

**When to use:** For apps that connect to Ollama, OpenAI-compatible APIs, local models, or multiple AI providers.

#### Prompt
```text
Review the provider/model settings in this app.

Check:
- provider list clarity
- local vs cloud distinction
- base URL handling
- API key storage
- model selection
- default provider
- connection test behavior
- error messages
- what can be hardcoded for v1
- what settings should wait

Rules:
- keep provider setup simple
- do not add unnecessary provider abstractions
- protect secrets
- prefer clear failure messages
- support local-first usage where possible
```

### Step-by-Step Agent Run

> Force the agent into small numbered steps with a clear stop after each one.

**When to use:** When the task is risky, touches many files, or you want Agent to stop after each clear step.

#### Prompt
```text
Work in small numbered steps.

For each step:
- say the step number
- explain what you are about to change
- change only the files needed for that step
- summarize what changed
- say "ready for next" before continuing

Rules:
- do not skip steps
- do not combine unrelated changes
- do not start the next step until the current one is clearly complete
- stop if you find a risk or ambiguity
```

### SwiftUI State Cleanup

> Find the simplest state structure for a small macOS app and make the source of truth obvious.

**When to use:** When a SwiftUI view has too many @State, @Binding, ObservableObject, environment values, or weird refresh bugs.

#### Prompt
```text
Review the SwiftUI state management in this app.

Look for:
- too much state in views
- duplicated state
- bindings passed too deeply
- objects that should be local
- objects that should be shared
- confusing source of truth
- unnecessary view models
- refresh or update risks

Suggest the simplest state structure for a small macOS app.

Rules:
- do not introduce architecture patterns unless needed
- avoid fake scalability
- prefer readable SwiftUI
- keep the fix small
- explain what owns each piece of state
```

### Vault Reference Review

> Make a note skimmable and reusable as an Obsidian reference — no long essays.

**When to use:** When creating notes, prompt libraries, YAML references, checklists, or project docs meant to live in a vault.

#### Prompt
```text
Review this as an Obsidian/vault reference note.

Check:
- clear title
- useful headings
- short intro
- practical examples
- YAML block if helpful
- tags if useful
- internal links if relevant
- no bloated explanation
- easy copy/paste sections

Rules:
- keep it skimmable
- prefer reusable blocks
- avoid long essays
- make it useful as a future reference
```

### MCP Tool Description Fixer

> Make the model call your tool correctly on the first try.

**When to use:** When a model skips your tool, calls it at the wrong time, or fills the params wrong.

#### Prompt
```text
Rewrite this MCP tool description so a model calls it correctly on the first try.

Fix:
- when to use it, and explicitly when not to
- what each param actually means, not just its type
- what it returns and in what shape
- failure modes and what the model should do about them

Cut anything the model does not need at call time.

Current description:
[paste]
```

### Agent Failure Modes

> Find where the loop fails silently instead of erroring.

**When to use:** Designing or reviewing a multi-step agent workflow — before it runs unattended.

#### Prompt
```text
Here is an agent workflow.

Identify where it fails silently rather than erroring:
- bad tool results treated as truth
- errors that compound through steps instead of surfacing
- retries that mask the real problem
- loops with no bound
- success reported without verification

For each: the detection signal, and the guard.

Workflow:
[paste]
```

### Context Diet

> Cut the context, keep the behavior.

**When to use:** When a system prompt or agent context has grown by accretion and nobody has removed anything in a while.

#### Prompt
```text
This context is too long.

Rank every section by how much it changes model behavior versus tokens it spends.
Cut the bottom 40%.

Show me:
- what you cut
- what you kept and why
- the one thing you were most nervous about cutting

Context:
[paste]
```

### Preference to Eval Assert

> Turn a taste into a machine-checkable test.

**When to use:** When you keep correcting the same thing by hand and it should be an assert instead.

#### Prompt
```text
Turn this preference into machine-checkable asserts for an eval harness.

Preference: [describe it]

Give me:
- the assert type (contains / not-contains / regex / llm-rubric)
- the exact assertion
- one passing and one failing example output

Prefer deterministic asserts over rubrics wherever possible. If it can only be a rubric, say why.
```

### Review Local-First Behavior

> Review-time local-first check: does it work offline?


#### Prompt
```text
Review this feature as a local-first workflow.

Check:
- whether core functionality works offline
- where data is stored
- whether users can inspect their files
- whether sync is optional
- whether cloud failure blocks local work
- whether exports are standard formats
- whether external providers are required unnecessarily
- whether local changes are immediately durable

Keep remote integrations additive.

Do not make cloud availability a requirement unless the feature fundamentally depends on it.
```

### Review AI Features for Product Fit

> Does the AI feature fit the product, or just exist?


#### Prompt
```text
Review every AI-powered feature in the current implementation.

For each feature, determine:
- what user problem it solves
- whether the user explicitly triggers it
- whether the result is editable
- whether failure blocks the core workflow
- whether local or private processing is possible
- whether the UI clearly distinguishes generated content
- whether cost and latency are appropriate
- whether a deterministic implementation would be better

Remove AI where it adds novelty but not practical value.

Keep the app useful when AI is unavailable.
```

### Review AI Action Placement

> Where AI actions belong in the interface.


#### Prompt
```text
Review where AI actions appear in the interface.

Prefer:
- contextual commands
- selected-text actions
- action menus
- inspector suggestions
- explicit user-triggered workflows

Avoid:
- permanent large AI panels
- chat interfaces for simple transformations
- AI buttons repeated in every row
- automatic generation without user control
- AI as the first action when a normal action is more reliable

Keep the core interface product-first, not provider-first.
```

### Review Provider-Specific UI

> Don't leak provider names into the product.


#### Prompt
```text
Review provider and model controls.

Check:
- whether provider selection belongs in Settings
- whether the current model needs to be visible
- whether technical details belong in the inspector
- whether provider errors are understandable
- whether model names are exposed unnecessarily
- whether fallback behavior is clear
- whether unavailable providers degrade gracefully

Keep provider management away from the main workflow unless switching providers is itself a frequent user task.
```

### Review Background Agent Activity

> Background agents the user can see and stop.


#### Prompt
```text
Review how background agents or automated processes appear in the app.

Show only useful information:
- current status
- current task
- progress
- last meaningful result
- errors requiring attention
- whether the process can be stopped

Avoid:
- excessive logs in the main interface
- animated activity indicators without meaning
- pretending the app controls an external agent when it only observes it
- unclear success states
- hidden file modifications

Keep detailed logs in a dedicated diagnostics or activity view.
```

### Review Activity Log Design

> Activity logs that are readable, not raw.


#### Prompt
```text
Review the activity log.

Check:
- useful event grouping
- timestamp precision
- filtering
- errors
- file changes
- agent actions
- user actions
- system actions
- copyability
- retention
- privacy
- empty state

The log should answer:
- what happened
- when
- what changed
- whether action is required

Do not use the activity log as a substitute for clear status in the main interface.
```

### Review Terminal Integration

> Terminal integration done deliberately.


#### Prompt
```text
Review the embedded terminal implementation.

Check:
- whether it is visually secondary
- whether opening it changes the main layout
- whether it spans the intended width
- whether it restores its open or closed state
- whether working directory is correct
- whether process termination is safe
- whether focus moves correctly
- whether shortcuts conflict with the editor
- whether output remains readable
- whether the terminal can be hidden without interrupting its process

Keep the terminal attached to the app but structurally separate from the main content.

Do not expose terminal controls as primary product actions.
```

---

## Docs & Continuity

### App TODOs & Future Features

> Keep TODO/ROADMAP small and honest — separate now from later, and don't let it balloon.

**When to use:** When the app has many ideas, unfinished tasks, or possible future features. Good for keeping TODO.md, ROADMAP.md, or FEATURES.md clean and not overbuilt.

#### Prompt
```text
Review and update the app TODOs and future features list.

Organize items into:
- critical fixes
- current v1 tasks
- polish tasks
- future features
- ideas to delay
- ideas to reject or remove

For each item, clarify:
- why it matters
- where it belongs
- whether it is needed before launch
- whether it can wait
- whether it risks overcomplicating the app

Rules:
- keep v1 small
- remove duplicate tasks
- merge similar ideas
- do not add features just because they sound useful
- mark uncertain ideas as "parking lot"
- make the next 3 tasks obvious
```

#### Variations
**Stricter version:**
```text
Inspect the current project and update TODO.md or create it if missing.

The TODO list should be practical for a solo developer.

Structure it as:
- Now
- Next
- Later
- Parking Lot
- Not Doing Yet

Rules:
- "Now" should contain only the next few concrete tasks
- "Next" should contain tasks that clearly follow v1
- "Later" should contain useful but non-urgent improvements
- "Parking Lot" should contain unvalidated ideas
- "Not Doing Yet" should contain features that may cause overengineering

Do not turn the TODO into a huge roadmap.
Do not add vague tasks.
Do not add future features unless they are clearly separated from current work.

At the end, summarize:
- what changed in the TODO
- what should be built next
- what should be delayed
```

### Do Not Touch Guardrail

> Name the protected areas before a run — what to edit, what to avoid — and confirm nothing protected changed.

**When to use:** Before any Agent run where certain files, UI areas, or working behavior must stay unchanged.

#### Prompt
```text
Before making changes, identify the protected areas of the project.

Do not touch:
- unrelated files
- working flows
- public APIs unless required
- visual design outside the requested area
- docs unrelated to this task
- generated files
- secrets or config files

For this task, first list:
- files you expect to edit
- files you will avoid
- behavior that must remain unchanged

After the task, confirm whether any protected area was changed.
```

### Empty State & Error Polish

> Make empty, loading, and error states short and clear — one obvious next action, no drama.

**When to use:** When an app feels rough because empty, loading, or error states are unclear.

#### Prompt
```text
Review and improve empty states, loading states, and error messages.

Check:
- first launch state
- no data state
- no search results
- loading state
- failed operation state
- offline/local model unavailable state
- missing permissions
- invalid settings

Rules:
- keep messages short
- explain what happened
- provide one clear next action
- avoid dramatic language
- do not add complex onboarding
```

### Multi-Agent Continuity

> Keep one source of truth across agents — flag conflicting instructions, make the next first step obvious.

**When to use:** When moving between Agent, Claude, Cursor, local models, or different agents working on the same repo.

#### Prompt
```text
Review this project for multi-agent continuity.

Check:
- whether docs explain current state
- whether AGENTS.md gives clear rules
- whether HANDOFF.md has exact next steps
- whether TODO.md separates now/later
- whether file naming is clear
- whether there are conflicting instructions
- whether generated changes are easy to audit

Rules:
- remove or flag conflicting instructions
- keep one source of truth for session state
- make the next agent's first step obvious
- avoid duplicating the same information in many files
```

### Permissions & Privacy Review

> Check what the app reads, writes, and stores — keep it local-first and make destructive actions explicit.

**When to use:** When an app touches files, folders, contacts, calendar, email, AI providers, API keys, screenshots, or local databases.

#### Prompt
```text
Review this app for permissions and privacy clarity.

Check:
- what data the app reads
- what data the app writes
- where data is stored
- whether API keys are protected
- whether files are modified safely
- whether user confirmation is needed
- whether permissions are explained clearly
- what should stay local

Rules:
- prefer local-first behavior
- avoid collecting unnecessary data
- make destructive actions explicit
- keep privacy explanation clear and short
```

### Prepare HANDOFF.md

> Write or refresh HANDOFF.md so the next run can continue without rereading the whole chat.

**When to use:** At the end of a Agent session, before stopping work, before switching agents, or before zipping/sharing a project. Creates a clear continuation point.
**Also linked from:** Session Control

#### Prompt
```text
Prepare or update HANDOFF.md for the next Agent run.

Include:
- project goal
- current state
- what was completed in this session
- what files were changed
- what still does not work
- important decisions made
- constraints the next agent must respect
- known bugs or fragile areas
- exact next steps
- what NOT to touch yet

Rules:
- be factual, not optimistic
- do not claim unfinished work is done
- keep it concise but complete
- mention commands that were run, if relevant
- mention commands that still need to be run, if relevant
- make it possible to continue without rereading the whole chat

At the end, add a short "Next safest step" section.
```

#### Variations
**Stricter version:**
```text
Inspect the repository and prepare a practical HANDOFF.md for the next agent/developer.

The handoff must answer:
- What is this app?
- What works right now?
- What changed in the latest session?
- What is unfinished?
- What files matter most?
- How should the next session start?
- What should be avoided?

Do not write marketing copy.
Do not invent progress.
Do not include vague phrases like "improve the app" without specific tasks.
Prefer clear bullet points and exact file paths.
```

### Public Share Readiness

> Get a small app ready to share publicly — honest about limits, no hype, blockers separated from polish.

**When to use:** Before sharing a small app publicly, on GitHub, Product Hunt, social media, or with friends.

#### Prompt
```text
Review this app for public sharing readiness.

Check:
- clear one-sentence description
- screenshots or demo readiness
- README clarity
- install/run instructions
- known limitations
- license if relevant
- obvious bugs
- privacy notes
- first-use experience

Rules:
- be honest about limitations
- do not add hype
- keep the public description simple
- separate launch blockers from later polish
```

### Read HANDOFF.md

> Make the agent read HANDOFF.md and treat it as the source of truth before it writes any code.

**When to use:** At the start of a Agent session, after reopening a project, or when switching between agents. Prevents the next run from guessing the project state.

#### Prompt
```text
Read HANDOFF.md first and treat it as the source of truth for this session.

Identify:
- project goal
- current state
- completed work
- unfinished tasks
- important constraints
- files that matter
- risks or unclear areas
- the next safest step

Do not start coding yet. First summarize what you understood and say what you would do next.
```

### Remove AI Slop

> Strip the generic copy, fake structure, and vague abstractions an AI added — keep the real work.

**When to use:** When Agent or another AI added too much generic copy, vague abstractions, fake polish, or unnecessary structure.

#### Prompt
```text
Review this project for AI-generated bloat.

Find and reduce:
- generic marketing language
- vague comments
- unnecessary abstractions
- fake enterprise structure
- unused helper files
- overexplained docs
- repetitive TODOs
- features that were added without clear need

Rules:
- keep useful work
- remove only what is clearly unnecessary
- prefer direct names
- make the project feel hand-built and intentional
- explain what was removed and why
```

### Repo-to-Agent Handoff

> Prepare a repo for safe Agent work the first time you open it — without inventing features.

**When to use:** When opening a repo for the first time and preparing it for Agent work.

#### Prompt
```text
Inspect this repo and prepare it for safe Agent work.

Create or update:
- README.md if missing or unclear
- AGENTS.md with repo-specific rules
- TODO.md with current next tasks
- HANDOFF.md with current state

First report:
- what kind of project this is
- how it appears to run
- important folders/files
- risks or missing setup

Rules:
- do not invent features
- do not rewrite everything
- do not make large code changes
- focus on making the repo understandable and safe to edit
```

### Small Refactor Plan

> Plan a one-run cleanup of the one or two areas that need it most — no giant refactor, no behavior change.

**When to use:** When code needs cleanup but you do not want a giant refactor.

#### Prompt
```text
Create a small refactor plan for this codebase.

Identify:
- one or two areas that need cleanup most
- why they matter
- the smallest safe refactor
- files involved
- tests or manual checks needed
- what not to refactor now

Rules:
- do not refactor for style only
- do not change behavior
- do not create new architecture layers
- keep the plan suitable for one Agent run
```

### Stop Building

> Ask whether to stop building for now — separate real blockers from polish and procrastination.

**When to use:** When you suspect you are adding more because it is interesting, not because the app needs it.

#### Prompt
```text
Review this project and tell me if I should stop building for now.

Identify:
- what is already enough
- what is blocking usefulness
- what is just polish
- what is procrastination disguised as improvement
- what should be cut
- what should be shipped or tested now

Return:
- stop now / continue briefly / not ready
- reason
- only the next action that matters
```

### Update All Docs

> Update only the docs that actually need it — no invented features, no marketing language.

**When to use:** After a coding session, before handing off to another agent, before zipping/sharing a project, or when docs are outdated.

#### Prompt
```text
Update all relevant project docs based on the current state of the codebase and recent changes.

Check and update where relevant:
- README.md
- HANDOFF.md
- TODO.md
- AGENTS.md
- CHANGELOG.md
- docs/
- setup or install instructions
- architecture notes
- known limitations

Rules:
- do not invent features
- remove outdated instructions
- keep docs concise
- mark unfinished work clearly
- make the project understandable for the next Agent run
- summarize what files you changed and why
```

#### Variations
**Stricter version:**
```text
Before editing, inspect the repository and identify which documentation files are actually relevant.

Then update only the docs that need changes.

Focus on:
- what changed
- what works now
- what is still unfinished
- how to run or test the project
- what the next agent/developer should know

Do not rewrite docs unnecessarily.
Do not add marketing language.
Do not claim completed work unless the code confirms it.
At the end, list every doc file changed and the reason.
```

### Comments That Earn Their Keep

> Delete the whats. Keep only the whys.

**When to use:** After an agent run — agents generate comments that narrate the code line by line.

#### Prompt
```text
Review the comments in this code.

Delete every comment that restates what the code already says.
Keep or add only comments that explain:
- why, not what
- non-obvious constraints
- a decision a future reader would otherwise undo

Show the diff and a count of what you removed.

Code:
[paste]
```

### Chesterton's Line

> This looks wrong but someone wrote it on purpose. Find out why first.

**When to use:** Before deleting something that looks pointless in code you did not write — including code you wrote a year ago.

#### Prompt
```text
This line looks wrong but someone wrote it deliberately.

Given the code and surrounding context, reconstruct:
- the most likely reason it exists
- what breaks if I remove it
- what evidence I should look for in history to confirm before deleting

Do not tell me to just delete it.

Code:
[paste]
```

### Review Documentation After Code Changes

> Find docs the last change made wrong.


#### Prompt
```text
Review the latest code changes and identify documentation that is now missing or outdated.

Check:
- README
- setup instructions
- architecture notes
- feature documentation
- settings documentation
- permissions
- environment variables
- known limitations
- screenshots
- handoff notes
- TODO and roadmap files

Only update documentation affected by the current change.

Remove instructions that no longer match the app.
```

### Update the Project TODOs

> A task list where every item is finishable.


#### Prompt
```text
Review the current code, recent changes, and existing TODO files.

Create or update a focused task list containing:
- bugs
- incomplete current work
- required cleanup
- documentation tasks
- safe next features
- deferred ideas
- decisions that need human input

Remove:
- completed tasks
- duplicate tasks
- stale tasks
- vague tasks with no clear outcome

Each task should be small enough to complete and verify in one focused run.
```

---

## Snippets

### Quick Snippets

> Short, fire-and-forget prompts — gates and rituals you paste mid-flow without ceremony. The longer, structured versions live in Session Control and Guardrails & Final.


---

#### Analyze → Decide → Execute

**When to use:** You want a tight loop with an approval gate before any change.

```text
1. Analyze the current implementation.
2. List the biggest UX + architecture issues.
3. Propose the smallest high-impact improvement.
4. Wait for execution approval.
5. Execute the approved direction only.
6. Do not expand scope.
```

---

#### Rethink

**When to use:** A feature feels heavier than it should. Reset to first principles.

```text
Rethink this feature from first principles.

Goals:
- fewer clicks
- simpler structure
- less configuration
- calmer UI
- smaller implementation

Challenge assumptions.
```

---

#### Audit (no code yet)

**When to use:** Opening a project and you want a read before touching anything.

```text
Do not code yet.

Audit this project for:
1. broken setup
2. missing docs
3. unclear architecture
4. security risks
5. easiest next win
```

---

#### Need This Now?

**When to use:** A YAGNI gate before implementing anything that smells optional.

```text
Before implementing:

1. Is this required to achieve the current milestone?
2. Can it be deferred?
3. Does it add complexity?
4. Is there a simpler version?

Answer:

REQUIRED_NOW: YES|NO
CAN_DELAY: YES|NO
SIMPLER_OPTION: <one sentence>
```

---

#### Between Runs (YAGNI audit)

**When to use:** You feel the urge to keep building. Stop and challenge the plan first.

```text
STOP.

Before doing any more work, audit the project and challenge the current plan.
Your job is NOT to continue building yet.

Review:
- Current codebase
- Recent changes
- AGENTS.md
- README.md
- Existing TODOs
- Project goals

Then determine:
1. What is already completed.
2. What is truly required for the next milestone.
3. What work is optional and can be postponed.
4. What files, features, docs, abstractions, folders, or tasks add complexity without immediate value.
5. What should be moved to /futurefeatures.
6. What should be removed entirely.

Apply strict YAGNI principles:
- No future-proofing.
- No premature abstractions.
- No placeholder systems.
- No features without an immediate use case.
- No documentation that isn't needed right now.

Output only:

# KEEP NOW
- items required for the next milestone

# DELAY
- items that can wait
- reason for delaying each item

# REMOVE
- items that should be deleted
- reason for deletion

# NEXT SINGLE ACTION
The one highest-impact task that should be done next.

# UPDATED PRIORITY ORDER
1.
2.
3.
4.
5.

Do not write code. Do not modify files. Audit only.
```

---

#### Start Session

**When to use:** First prompt when reopening a project. (Fuller version: Session Control.)

```text
Read:
1. AGENTS.md
2. CURRENT.md
3. TO-DO.md
4. README.md

Determine:
- Current project state
- Next logical task
- Missing documentation
- Risks

Do not start coding until you summarize findings.
```

---

#### End Session

**When to use:** Before stopping, to leave a clean continuation point. (Fuller version: Handoff & Docs.)

```text
Before ending:
1. Update CURRENT.md
2. Update TO-DO.md
3. Update README.md if needed
4. Update .meta/handoff.json

Provide:
- What was completed
- What remains
- Recommended next task
```

---

## Cogito Notes

### Add Frontmatter

> Add title/status/tags YAML frontmatter inferred from the note, without touching the body.

**When to use:** A note has no frontmatter and you want a consistent title/status/tags block inferred from its content.

#### Prompt
```text
Add YAML frontmatter to the top of this note with: title (from the first heading), status (in-progress), and tags (3–5 lowercase hyphenated tags inferred from the content). Put the opening --- on line 1 with nothing before it. Don't touch the body.
```

### Clean Up a Messy Paste

> Fix broken wraps, junk characters, and whitespace from a messy paste or OCR — without touching the actual words.

**When to use:** A note is pasted/OCR'd text full of broken line wraps, duplicate fragments, and junk characters.

#### Prompt
```text
This note is messy pasted text. Clean it up in place: fix broken line wraps, join split sentences, remove duplicate fragments and junk characters, and normalize whitespace. Do not change any actual words. If something is ambiguous, leave it and flag it with a TODO comment instead of guessing.
```

### Extract Action Items to the Top

> Surface the concrete action items into a "## Next" checklist at the top; leave the body alone.

**When to use:** You want the to-dos hoisted to the top of a note without restructuring the rest of it.

#### Prompt
```text
Scan this note and add a "## Next" checklist at the very top listing only the concrete action items you find below, as - [ ] items. Leave the rest of the note untouched. If there are no clear actions, say so in the chat instead of editing.
```

### Find & Adapt a Prompt

> Search this prompt folder for a topic, show the closest match, and hand back an adapted copy — read-only.

**When to use:** From inside Cogito, when you want to pull a prompt out of this library and adapt it to the current project without leaving the chat. This is the prompt that makes the whole library usable in place.

#### Prompt
```text
Search this folder for prompts related to [TOPIC]. Show me the closest match in the chat, then give me an adapted version with [PROJECT/CONTEXT] swapped in. Don't edit any files — just hand me the adapted prompt to copy.
```

#### Notes
- Swap `[TOPIC]` and `[PROJECT/CONTEXT]` before sending. Keep this folder as Cogito's Prompts Location so the agent can find and adapt anything in it.

### Notes into a Weekly Update

> Turn rough notes into a weekly update — progress, risks, and next steps.

**When to use:** You have scattered notes from the week and need a clean status write-up.

#### Prompt
```text
Turn these notes into a weekly update with progress, risks, and next steps.
```

### Outline a Long Note

> Add a heading structure and a top-of-note outline so a long note is navigable — body untouched.

**When to use:** A long note has no headings and you want it navigable in the Inspector without rewriting the content.

#### Prompt
```text
Read this whole note and add a heading structure so it's navigable in the Inspector. Insert H2/H3 headings where topics shift, keep the original text under each, and add a short "## Outline" list of links to the sections at the top. Don't rewrite the body.
```

### Rewrite Text Clearly

> Rewrite text to be clear, respectful, and concise for a professional setting.

**When to use:** Cleaning up a message, doc, or note before it goes to someone else.

#### Prompt
```text
Rewrite the following text so it is easier to understand. The text will be used in a professional setting. Ensure the tone is clear, respectful, and concise.

Text: [paste text]
```

### Rough Notes into a Draft Post

> Reshape rough notes into a draft blog post in your direct, minimal voice — saved in place as the draft.

**When to use:** A note holds rough thoughts you want shaped into a first blog draft, kept in your voice, before moving it to the real pipeline.

#### Prompt
```text
Turn this note into a draft blog post in plain Markdown: a hook opening line, 3–5 short sections with headings, and a closing line. Keep it in my direct, minimal voice — no hype, no emojis. Save it in place as the draft; I'll move it to the real pipeline myself when it's done.
```

### Rough Notes into a Task List

> Turn the action lines in a note into a Markdown checklist, grouped under existing headings — no invented tasks.

**When to use:** A note has action-oriented lines buried in prose and you want them as checkboxes.

#### Prompt
```text
Convert the action-oriented lines in this note into a Markdown checklist using - [ ] items. Leave context and headings as prose. Group tasks under their existing section headings. Don't invent tasks that aren't already implied here.
```

#### Variations
**Split by state (done vs. not):**
```text
Convert the action lines in this note into a checklist. Put anything already done as - [x], everything else as - [ ], grouped under their existing headings. Leave context as prose. Don't invent tasks.
```

**Flat "do next" block at the top:**
```text
Scan this note and add a "## Tasks" checklist at the top with only the concrete actions from below, as - [ ] items, shortest first. Leave the body untouched. If nothing's actionable, say so instead of editing.
```

**Tasks plus a Notion-ready copy:**
```text
Turn the action lines into a - [ ] checklist in place. Then in the chat (not the file), print the same items as plain lines I can paste into my Notion inbox. Don't invent tasks.
```

### Structure Raw Text into Markdown

> Impose clean Markdown structure on a note in place — headings, sections, lists — without changing the wording.

**When to use:** A note is raw text that needs heading hierarchy, sections, and lists, but the words should stay exactly as written.

#### Prompt
```text
Restructure this note into clean Markdown in place. Add a clear heading hierarchy, group related lines into sections, turn obvious lists into bullet or numbered lists, and fix spacing. Keep my wording and meaning exactly — do not add new content or opinions. Just impose structure.
```

### Tighten & Condense

> Get a tighter version that keeps every point and your voice — shown in chat first, applied only on approval.

**When to use:** A note is wordy or repetitive and you want it cut down without losing any distinct point or your tone.

#### Prompt
```text
Show me a tighter version of this note before changing anything. Cut filler and repetition, keep every distinct point, and preserve my voice. Print the rewrite in the chat first; only apply it to the file if I say go.
```

---

## Agent Prompts

### Agent Operating Rules

> A short, portable set of ground rules to paste into an agent's AGENTS.md or system prompt — the reusable spine distilled from a much longer system-prompt reference.

**When to use:** Setting up a new agent, repo, or AGENTS.md and you want sane default behavior without writing it from scratch.

#### Prompt
```text
Operating rules:

- Think before acting. Reason through the task before calling tools or writing; match the depth to the complexity.
- Decide and proceed. On a non-destructive choice, make a reasonable call and continue — don't stall to ask.
- Confirm destructive actions. Deleting, overwriting, or moving always needs explicit confirmation first.
- Read before you write. Inspect the current state before editing anything.
- Make surgical edits. Prefer focused changes over rewrites; preserve existing structure, naming, and comments.
- Prefer the dedicated tool. Use the native/specific tool for the job; fall back to a shell only when needed, and say why.
- Stop at risk or ambiguity. For risky or multi-step work, pause and ask rather than guessing.
- Stay in scope. Gather just enough context to act, then act; don't expand the task or over-explore.
- Be truthful over agreeable. Report what actually happened — failed tests, skipped steps — and never claim unverified success.
- Protect secrets and privacy. Never echo secrets or personal data; keep things local-first where you can.
- Fail in plain language. Retry transient errors a couple of times, then change approach; explain failures plainly, no raw stack traces unless asked.
- Match format to the question. Plain answer for a simple ask; add structure only when it genuinely helps.
```

#### Notes
- Distilled from `-raw/Desktop Commander/_source/desktop-commander-pre-build-prompts-by-category.md`. Trim to the rules that fit your agent.

### Balanced 1-Page Briefing

> A one-page, source-backed briefing on a topic: points of agreement, disagreement, and the open question.

**When to use:** You want a fair, shareable read on a topic before forming a view or briefing a team.

#### Prompt
```text
Research [topic] across multiple public sources and write a balanced 1-page briefing: 3 points of agreement, 2 points of disagreement, 1 open question. Include source links and a one-line confidence note. No hype, no hedging filler.
```

### Best Recent Articles on a Topic

> The 5 most useful recent articles on a topic, each boiled to its claim, support, and link.

**When to use:** You want a fast, ranked reading list on something — not a wall of search results.

#### Prompt
```text
Find the 5 most useful articles on [topic] from the last [week]. For each, extract the main claim and 2 supporting points, and give me the link. Rank by usefulness, not recency alone. Don't pad the list to hit a number.
```

### Build a Small Local Tool

> A single-file, dependency-free tool (form → local CSV) with a tiny run-it README.

**When to use:** You need a quick personal/team utility that doesn't deserve a backend or a build step.

#### Prompt
```text
Build me a single-file HTML form (no build step) that saves each submission to a local CSV. Fields: [list them]. Include a tiny README on how to run it locally. Keep it dependency-free — no backend.
```

### Citation Graph

> A self-contained HTML citation graph of a set of papers — nodes are papers, edges are citations.

**When to use:** You want to see how a cluster of papers cite each other, centered on a key one.

#### Prompt
```text
Build a citation graph of the [25] papers in [collection]: nodes are papers, edges are "cites", centered on [this paper]. Fetch citation data from open sources (Crossref / OpenCitations / Semantic Scholar) and save it as a single self-contained HTML file. Tell me if a source is unreachable instead of leaving gaps silently.
```

### Clean Build Artifacts Safely

> List build/cache directories with sizes, back them up, and delete only on approval.

**When to use:** A project is bloated with regenerable build output and caches you want gone safely.

#### Prompt
```text
Find build artifacts and caches in this project (node_modules, dist, .next, __pycache__, build, etc.). List each with its exact size. Zip everything to a timestamped backup folder first, then delete only after I say go. Don't touch source or config.
```

### Daily Folder-Summary Job

> A daily scheduled job that summarizes the last 24h of a folder into a dated note — local only.

**When to use:** You want a hands-off daily record of what landed in a folder. *(Needs a local scheduler.)*

#### Prompt
```text
Set up a daily job: every morning at [9am], scan [folder] for files modified in the last 24 hours, summarize them, and write the summary to a dated note in [folder]. Use the local scheduler, not a cloud service. Only write the file — don't email or notify.
```

### Diff Two Spreadsheets

> A row-by-row diff of two file versions — new, deleted, and changed values — exported as a new file.

**When to use:** Two versions of a spreadsheet (budget Q1 vs Q2, before/after) and you need exactly what changed.

#### Prompt
```text
Compare [file A] and [file B] row by row. Highlight new rows, deleted rows, and changed values. Export the diff as a new file in [output folder]. Don't modify either original.
```

### Explain a Codebase

> One plain-English paragraph on what a project does and how it's structured, plus a folder map.

**When to use:** Opening an unfamiliar repo and you want orientation before touching anything.

#### Prompt
```text
Read the top-level files of this project (README, manifest/package files, main entry points) and explain in one plain-English paragraph what it does and how it's structured. Add a small map of the main folders. Be specific to this repo — no generic boilerplate.
```

### Export BibTeX

> Export a Zotero collection to BibTeX (or CSL-JSON/RIS) with a manifest of what was included and skipped.

**When to use:** You're writing a paper and need a clean bibliography file from a collection.

#### Prompt
```text
Export the items in my [collection] as a [BibTeX / CSL-JSON / RIS] file to [output folder]. Include a manifest of what was exported and what was skipped and why. Don't modify the library.
```

### Extract Invoice Fields to a Table

> Pull structured fields from a folder of invoices into one CSV — flag what won't parse, don't guess.

**When to use:** You have many invoices/receipts (PDF or CSV) and need one clean table out of them.

#### Prompt
```text
Read every PDF/CSV in [folder] and return one table with a row per document: vendor, date, total, email (adjust columns as needed). Save the table as a CSV in [output folder]. Flag any document you couldn't parse instead of guessing.
```

### Find Broken Wikilinks

> A report of every broken or renamed wikilink in a vault, with a suggested fix — nothing edited.

**When to use:** A long-running vault has accumulated broken `links` you want found before fixing.

#### Prompt
```text
Audit wikilinks across my vault: for each target, confirm the target note exists. List every broken or renamed link with the note it's in, and suggest either creating the target or fixing the link. Don't edit anything yet — just the report.
```

### Find Duplicate Files by Content

> Detect duplicates by content hash (not filename), recommend which to keep, and delete nothing without approval.

**When to use:** You suspect duplicate files scattered across a folder and want a safe keep/remove list.

#### Prompt
```text
Find duplicate files in [folder]. Detect duplicates by content hash, not just filename. Group them by size, and for each group recommend which copy to keep and why. Don't delete anything — wait for my explicit go on each group.
```

### Find Every Use of a Function

> An exhaustive list of every reference to a function or symbol — for safe refactors and deletions.

**When to use:** Before renaming, changing, or deleting a function and you need every call site.

#### Prompt
```text
Find every place [function/symbol] is used. Return a list of every file and line that references it, grouped by file. This is for a refactor, so be exhaustive — include indirect references and string usages if any.
```

### Group Recent Files by Topic

> Cluster recently-touched files by topic and propose a folder layout — preview before moving.

**When to use:** A pile of recent files (contracts, receipts, research) needs sorting by what they're about, not just type.

#### Prompt
```text
Find files in [folder] modified in the last [30] days, sample each one, and cluster them by topic (e.g. contracts, receipts, research). Return a proposed folder layout to move them into. Don't move anything yet — show me the plan first.
```

### Highlights to a Study Note

> Turn one paper's highlights into a 1-page study note — citation, summary, then highlights grouped by theme.

**When to use:** You've highlighted a PDF and want a clean, reusable study note out of it.

#### Prompt
```text
Pull all my highlights from [paper/PDF] into a 1-page study note: citation at the top, a one-paragraph summary, then the highlights grouped by section or theme in reading order. Save it to [folder].
```

### Map the Vault

> A one-page map of an Obsidian vault — folder shape, top tags, and orphan notes. Read-only.

**When to use:** A vault has grown for years and you can't see its structure anymore.

#### Prompt
```text
Scan my Obsidian vault at [path] and return a 1-page map: the folder structure, the most-used tags, and a list of orphan notes (no incoming links). Read-only — don't change anything.
```

### Merge Duplicate Zotero Items

> Merge duplicate Zotero items into the richer record (keep the PDF), folding in stray tags and notes — preview first.

**When to use:** The same paper appears twice in Zotero and you want one clean record.

#### Prompt
```text
Merge these duplicate Zotero items [selection, or auto-detect by DOI]. Keep the richer record (with PDF and notes), preserve its attachments, and fold in any tags or notes the duplicate had that the keeper didn't. Show me a preview of the merge before doing it.
```

### Morning Briefing

> A one-screen morning digest from your calendar, email, and to-dos — only the sources you've connected.

**When to use:** You want a single calm start-of-day view. *(Needs those sources connected + a scheduler.)*

#### Prompt
```text
Each morning at [7:30], build a one-screen briefing from my [calendar], [email subject lines], and [top 3 to-dos]. Pull only from sources I've already connected. Keep it to one screen — headings, no padding.
```

### Organize a Project Folder

> Propose a flat, human-readable structure and naming convention so anything is findable in seconds.

**When to use:** A project folder has grown messy and you want a simple, predictable layout.

#### Prompt
```text
Reorganize [folder] so I can find anything in ~10 seconds. Propose a flat, human-readable structure (e.g. 01_inbox, 02_in_progress, 03_done, 04_archive) and a naming convention. List the proposed moves before making them; don't create deep folder trees.
```

### PDF to Zotero Item

> Turn a loose PDF into a proper Zotero item — metadata, attachment, tags — confirmed before it's written.

**When to use:** You have a PDF that isn't in Zotero yet and want it filed correctly.

#### Prompt
```text
Read this PDF and create a Zotero item from it: extract title, authors, year, abstract, and DOI, attach the PDF, and add 3–5 tags from [my tag list]. Confirm the metadata with me before writing it to the library.
```

### Privacy-Scan a Folder Before Sharing

> Flag PII before you share a folder, score each file, and redact or move — never echo the raw value.

**When to use:** Before sending or publishing a folder that might contain personal data.

#### Prompt
```text
Before I share [folder], scan it for anything personal: SSN-shaped numbers, email addresses, phone numbers, home addresses, API keys. Return a per-file risk score and a redacted preview. Never paste the raw sensitive value back to me — only counts and categories. Then ask whether to redact in place or move the sensitive files aside.
```

### Rank Connected vs Dead-End Notes

> The top hub notes and the most isolated ones — to see what to build around and what to prune.

**When to use:** Before refactoring or pruning a vault, when you want to find its hubs and dead-ends.

#### Prompt
```text
Rank the notes in my vault by connectedness: return the top 10 by backlinks (hubs) and the top 10 with no/few links (dead-ends). This is to plan a refactor, so add a one-line note on why each hub matters. Read-only.
```

### Reading Pattern Synthesis

> What your recent reading actually looks like — top authors, common topics, and a 3-sentence pattern. Read-only.

**When to use:** You want to see the shape of your own reading across a stretch of papers.

#### Prompt
```text
Across the last [30] items in [collection], tell me the 5 most-cited authors and the 5 most common topics, and describe my actual reading pattern in 3 sentences (what, from where, what era). Read-only.
```

### Resurface To-Process Notes

> Surface the old tagged backlog with a one-line summary each and three actions — you choose per note.

**When to use:** You have a long backlog of half-processed notes under a tag you keep meaning to clear.

#### Prompt
```text
Find every note in my vault still tagged `#to-process` (or [your tag]). List each with a one-sentence summary, and for each offer three actions: archive, rewrite into a permanent note, or delete. Don't act until I choose per note.
```

### Rewrite a Weak Prompt

> Rewrite a prompt that underperformed and explain the three specific changes, so you learn the pattern.

**When to use:** A prompt didn't work and you want both a better version and the reasoning behind it.

#### Prompt
```text
Here's a prompt that underperformed: [paste it]. Rewrite it to be clearer and more specific, then explain the 3 specific changes you made and why, as a before/after. Goal is for me to learn the pattern, not just get a better one-off.
```

### Run Tests, Show Only Failures

> Run the suite and surface only the failures — file, line, and the real error — no passing noise.

**When to use:** After a change, when you want a clean list of what broke without scrolling through green.

#### Prompt
```text
Run this project's test suite and show me only what failed: file, line, and the actual error message for each failure. Filter out all passing tests and noise. Don't try to fix anything yet.
```

### Scan for Committed Secrets

> Severity-ranked scan for committed keys, tokens, and .env files — without ever echoing the secret.

**When to use:** Before pushing, sharing, or open-sourcing a repo that might contain credentials.

#### Prompt
```text
Scan [folder/repo] for accidentally committed secrets (API keys, tokens, private keys, .env files). Return a severity-ranked list with the file and line, and recommend the next safe step for each. Never echo a secret value back to me — only its type and location.
```

### Split a Zotero Collection

> Propose a Topic/Method/Project subcollection layout for a catch-all collection — create empty, move only on approval.

**When to use:** A single "To sort" / "Catch-all" Zotero collection has grown unmanageable.

#### Prompt
```text
Take my [collection name] collection and propose a 3-level subcollection layout (Topic / Method / Project) based on each item's tags, abstract, and outlet. Create the empty subcollections, but don't move any items until I approve the plan.
```

### Summarize a Long PDF

> A 2-minute read of a long document: short summary, top findings, and the questions it leaves open.

**When to use:** A report, paper, or contract is too long and you want the gist plus what's unanswered.

#### Prompt
```text
Read [file.pdf] and return: a short summary, the 5 most important findings, and 3 questions the document raises but doesn't answer. Keep it to something I can read in 2 minutes.
```

### Sync Zotero Without Paid Storage

> Sync a Zotero library across devices without the paid plan — pick a local-first option and set it up.

**When to use:** You use Zotero on several machines and don't want to pay for Zotero Storage.

#### Prompt
```text
Help me sync my Zotero library across [Mac, iPad, Windows] without paying for Zotero Storage. Explain the realistic options (WebDAV file sync, linked attachments in a cloud folder, ZotFile) with their tradeoffs, then set up whichever I pick. Keep it local-first; don't suggest the paid plan unless I ask.
```

### Tidy a Folder by Type & Date

> Propose a type/date layout for a messy folder, move only on approval, and keep it reversible.

**When to use:** A folder (Downloads, Desktop, a project dump) has piled up and you want it sorted without risk.

#### Prompt
```text
Tidy this folder: [path]. Scan it, then propose a layout grouped by file type and date (e.g. PDFs/2026-06, Images/June, Installers). Show me the plan before moving anything. On approval, move the files and write a manifest so the move is fully reversible. Don't delete anything.
```

### Watch a Web Page for Changes

> Recurring check on a URL that reports only real text changes — ignoring banners, dates, and layout noise.

**When to use:** You want to know when a pricing page, policy, or listing actually changes. *(Needs a scheduler.)*

#### Prompt
```text
Check [url] every [6] hours. Compare the page text to the previous snapshot and report only real differences in plain language — ignore cookie banners, date stamps, and layout noise. Tell me when nothing meaningful changed, too.
```

### Weekly Shipped Report

> A weekly markdown report of commits and merged PRs across your repos — written to a file, nothing more.

**When to use:** You want an automatic end-of-week record of what you actually shipped. *(Needs a local scheduler + git repos.)*

#### Prompt
```text
Every [Friday at 4pm], scan my local git repos in [folder], collect the week's commits and merged PRs, and summarize them by repo into a markdown report saved to [folder]. Stop the moment the file is written — no email, no Slack.
```

### Write a Real README

> A README a new developer can actually follow — real commands from the repo, no marketing.

**When to use:** A project has no usable README, or the existing one is vague or out of date.

#### Prompt
```text
Write a README for this project that a new developer can actually follow: what it is, how to install, how to run, how to test, how to deploy. Pull the real commands from the repo — don't invent any. Keep it direct, no marketing.
```

### YouTube to 1-Page Summary

> A long video distilled to one page — overview, takeaways, and a jump-to timestamp for each.

**When to use:** A long talk, lecture, or podcast you'd rather read than watch.

#### Prompt
```text
For this YouTube link: [url], pull the transcript and produce a 1-page summary: a one-paragraph overview, 5 key takeaways, and a jump-to timestamp for each takeaway. Note if no transcript is available rather than inventing content.
```

### Zotero Library Overview

> A 1-page read on a Zotero library — top authors, oldest unread, largest collections. Read-only.

**When to use:** A reference library has grown to thousands of items and you feel lost in it.

#### Prompt
```text
Give me a 1-page overview of my Zotero library: total item count, the top 10 authors by count, the 10 oldest items still flagged unread, and the 5 largest collections. Read-only — don't change anything.
```

### Zotero Metadata Audit

> Find Zotero items with missing or broken metadata and propose fixes — show before/after, never auto-edit.

**When to use:** A library has accumulated items with missing DOIs, authors, or mangled titles.

#### Prompt
```text
Scan my Zotero library for items with missing or broken metadata: no DOI, missing author, missing date, duplicate DOIs, or an HTML title where a journal title belongs. List what's wrong per item and propose a fix. Show before/after — never auto-edit.
```

---

## Claude Library

### Get oriented in a new repository

> Describe what you want to know, not which files to read. Claude explores the project on its own and returns a summary of how it fits together.

**When to use:** Discover → Onboard

#### Prompt
```text
give me an overview of this codebase: architecture, key directories, and how the pieces connect
```

### Trace how code evolved

> Point at commit history when the question is why, not what. Claude reads the log and blame for whatever version control you use and explains the decisions behind the current implementation.

**When to use:** Discover → Understand

#### Prompt
```text
look through the commit history of internal/auth/session.go and summarize how it evolved and why
```

### Explain how a feature works end to end

> Trace a whole flow — UI down to data and back — in plain terms specific to this codebase.

#### Prompt
```text
walk me through what happens when a user [does X], from the UI down to the data and back. keep it concrete to this codebase, not generic.
```

### Find where something happens

> Locate the code behind a behavior when you don't know the file name.

#### Prompt
```text
where in this codebase do we [handle X]? show me the files and the key functions, and how they connect.
```

### Check what breaks before you change it

> See the blast radius of a change before touching anything.

#### Prompt
```text
if I change [X], what else depends on it and could break? list the call sites and downstream effects before I touch anything.
```

### Plan before you touch code

> Get an approach and a file list first — no edits yet.

#### Prompt
```text
plan how to [do X]. list the files you'd change and the order you'd do them in, but don't edit anything yet.
```

### Smallest first step

> Turn a big goal into one shippable move for today.

#### Prompt
```text
I want to [goal]. what's the smallest first step that gets something working end to end today? just that step.
```

### Stress-test my plan

> Poke holes in a plan before you commit to it.

#### Prompt
```text
here's my plan: [paste]. what am I missing, what's risky, and what would you cut to make it simpler?
```

### Build a tiny tool

> A single-file, no-framework utility you can run immediately.

#### Prompt
```text
build a single-file [tool] using HTML, CSS, and vanilla JavaScript, then open it in my browser.
```

### Reproduce, then fix a bug

> Lock the bug into a failing test before fixing it.

#### Prompt
```text
write a failing test that reproduces [bug], then fix the code until the test passes.
```

### Fix the root cause of this error

> Paste an error; get the real fix, not a band-aid.

#### Prompt
```text
here's an error: [paste]. find the root cause, fix it, and verify it's actually gone — no suppressions or band-aids.
```

### Make it deterministic

> Chase down flaky, sometimes-works behavior.

#### Prompt
```text
this sometimes fails: [describe what happens]. investigate why it's inconsistent and make it deterministic.
```

### Add just enough logging

> Insight into a code path without drowning in noise.

#### Prompt
```text
add minimal logging around [X] so I can see what's happening when it runs, without adding noise.
```

### Add a keyboard shortcut

> Wire a shortcut into a SwiftUI macOS app and its menu.

#### Prompt
```text
add a keyboard shortcut (e.g. Cmd+K) for [action] in this SwiftUI macOS app, and show it in the menu.
```

### Menu bar app scaffold

> Turn a macOS app into a status-bar app with a popover.

#### Prompt
```text
turn this into a menu bar macOS app: a status-bar item, a popover holding the main view, and a launch-at-login toggle.
```

### Clean up SwiftUI state

> Simplify state so there's one source of truth.

#### Prompt
```text
review the state in this SwiftUI view. simplify the @State / @Binding / @Observable usage and remove any redundant sources of truth.
```

### Make it feel native (macOS)

> Right control sizes, SF Symbols, focus order, standard spacing.

#### Prompt
```text
make this macOS view feel native: correct control sizes, SF Symbols, keyboard focus order, and standard spacing.
```

### Smooth out a janky view

> Find what's causing re-renders or hitches in SwiftUI and fix it.

#### Prompt
```text
this SwiftUI view feels janky. find what's causing extra re-renders or hitches and fix it.
```

### Review my changes before I commit

> A risk pass over your uncommitted work.

#### Prompt
```text
review my uncommitted changes and flag anything that looks risky before I commit.
```

### Release notes from git

> Draft a changelog from the commits between two points.

#### Prompt
```text
compare [v1] to [v2] and draft release notes grouped by feature, fix, and breaking change.
```

### Ready to ship?

> A quick pre-ship sanity pass.

#### Prompt
```text
do a pre-ship pass on this: does it build, any obvious bugs, leftover TODOs, or debug code I forgot to remove?
```

### Summarize a long note

> Key points, decisions, and open questions from a wall of text.

#### Prompt
```text
summarize this note into key points, decisions made, and open questions still to resolve.
```

### Suggest links for this note

> Find notes this one should connect to.

#### Prompt
```text
read this note and suggest 3-5 existing notes it should link to, with one line on why each.
```

### Turn this into a reusable command

> Capture a repeated task as a /command skill.

#### Prompt
```text
I do [task] a lot. turn it into a /command (skill) for this project that I can rerun.
```

### Name this well

> Better names for a function, type, or file — with reasons.

#### Prompt
```text
suggest 3 clearer names for [this function/type/file] and say why each is better. pick the one you'd ship.
```

### Play devil's advocate

> The strongest case against a decision you're leaning toward.

#### Prompt
```text
argue the strongest case against [decision]. what would make me regret it in three months?
```

### Rubber-duck this

> Get unstuck by being asked the right questions, one at a time.

#### Prompt
```text
I'm stuck on [problem]. ask me questions one at a time until we figure out what's actually going on.
```

### Draft a calm launch post

> A short, no-hype post about something you shipped.

#### Prompt
```text
draft a short, calm launch post for [thing] — no hype, just what it does, who it's for, and why I made it.
```

### Make this repo understandable

> Leave the codebase clearer than you found it.

#### Prompt
```text
what would make this repo easier to understand for someone opening it cold (including future me)? do the top few things.
```

### Works on my machine

> Diff the two environments systematically instead of guessing.


#### Prompt
```text
works in [env A], breaks in [env B]. enumerate every possible difference between them — versions, env vars, filesystem, timezone, locale, network, permissions, arch, clock, resource limits. rank by fit with the symptom. give me one command per candidate to check it.

symptom: [paste]
```

### Minimal repro

> Strip it until only the bug is left.


#### Prompt
```text
reduce this to a minimal reproduction. strip every line that isn't required to trigger the bug. after each cut, tell me whether the bug survives. end with the smallest repro and one sentence on what it proves.

[paste]
```

### Cut it until it hurts

> The smallest version that still teaches you something real.


#### Prompt
```text
here's what I want to build: [idea]. cut it to the smallest version that still teaches me something real. tell me what's in, what's explicitly deferred, and what question the first version answers. if the cut version answers no question, say so and cut differently.
```

### Build, buy, or ignore

> Three real options — and do-nothing is one of them.


#### Prompt
```text
for [need]: give me build, buy, and do-nothing as three real options. for each: true cost including maintenance, time to value, what it locks me into, exit cost. do-nothing is a real option — argue it properly. end with a recommendation and the condition that would flip it.
```

---

## Commands & Keyboard

### Convert Visible Actions Into a Command Menu

> Move visible buttons into a command menu.


#### Prompt
```text
Review all visible actions on this screen.

Classify each action as:
- primary and always visible
- contextual and suitable for a command menu
- destructive and suitable for a confirmation flow
- secondary and suitable for a context menu
- unnecessary
- better represented as a keyboard shortcut

Move appropriate actions into one consistent action menu.

For every action, define:
- command title
- keyboard shortcut, if justified
- enabled and disabled state
- whether it requires confirmation
- where it appears in the menu
- whether it should also exist in the macOS menu bar

Do not hide the primary action.

Do not assign shortcuts to rarely used commands.
```

### Review Command Palette Architecture

> Command palette architecture, reviewed.


#### Prompt
```text
Review the current command palette or command system.

Check:
- command discovery
- naming consistency
- grouping
- search quality
- keyboard navigation
- disabled states
- recent commands
- contextual commands
- duplicate commands
- command execution feedback
- menu bar integration

Separate commands into:
- global commands
- navigation commands
- selected-item actions
- creation commands
- settings commands
- destructive commands

Avoid turning simple text search into a complex command framework.

Keep command registration explicit and easy to maintain.
```

### Design a Native macOS Command Palette

> Design a command palette that feels native, not web.


#### Prompt
```text
Implement a native macOS command palette for the existing app.

The palette should support:
- opening with a standard shortcut
- fuzzy or forgiving search
- arrow-key navigation
- Return to execute
- Escape to dismiss
- visible keyboard shortcuts
- contextual commands
- disabled commands with clear reasoning where useful
- recent commands
- consistent icons using SF Symbols

Keep the visual structure compact.

Do not:
- add plugin architecture
- add nested command trees unless necessary
- add command categories that contain only one item
- duplicate normal text search
- use the palette as a replacement for basic navigation

Explain which commands are global and which depend on the current selection.
```

### Create a Shared Command System

> One command system behind menu bar, palette, and shortcuts.


#### Prompt
```text
Refactor repeated actions into a shared command system.

Each command should define:
- identifier
- title
- optional SF Symbol
- keyboard shortcut
- availability
- execution
- destructive status
- menu placement
- command-palette visibility
- context-menu visibility

Do not create an overly generic plugin framework.

The goal is to prevent duplicated action logic across:
- menu bar
- command palette
- toolbar
- context menus
- keyboard shortcuts
```

### Review Menu Bar and Command Palette Consistency

> Menu bar and palette should not disagree.


#### Prompt
```text
Compare the menu bar, context menus, command palette, toolbar, and shortcuts.

Check for:
- duplicate command definitions
- different names for the same action
- different shortcuts
- inconsistent enabled states
- commands missing from one surface
- actions implemented separately in multiple views
- destructive actions placed inconsistently

Create one command definition per action where practical.

Each surface should present the same behavior with context-appropriate placement.
```

### Audit Menu Bar Commands

> Audit the menu bar against real macOS structure.


#### Prompt
```text
Review the macOS menu bar structure.

Check:
- App menu
- File
- Edit
- View
- Navigate
- Window
- Help
- custom menus

Identify:
- commands placed in the wrong menu
- duplicated commands
- missing standard commands
- actions available only through custom UI
- incorrect separators
- inconsistent naming
- shortcuts not represented in menus
- disabled states that are not contextual

Follow standard macOS menu organization.

Do not create custom top-level menus unless the app has a strong product-specific reason.
```

### Review Command Naming

> Command names that say what they do.


#### Prompt
```text
Review all user-facing command names.

Use:
- clear verbs
- concise labels
- consistent terminology
- standard macOS language where appropriate

Prefer:
- New Note
- Open Folder
- Rename
- Move to Trash
- Reveal in Finder
- Show Inspector
- Hide Sidebar
- Copy Path

Avoid:
- Execute
- Process
- Manage
- Handle
- Perform Action
- Run Operation
- Delete Permanently, unless it is actually permanent

Do not expose implementation terms such as model names, service names, or internal identifiers unless the user needs them.
```

### Review Keyboard Shortcuts Against macOS HIG

> Shortcuts checked against the HIG, including conflicts.


#### Prompt
```text
Audit all keyboard shortcuts in the app against macOS conventions.

Check:
- conflicts with standard system shortcuts
- conflicts with text editing
- inconsistent use of Command, Option, Control, and Shift
- shortcuts assigned to low-value actions
- missing shortcuts for frequent actions
- shortcuts that are difficult to remember
- duplicate shortcuts
- shortcuts unavailable from the menu bar
- shortcuts not displayed in action menus
- different shortcuts for the same action in different screens

Prefer:
- Command for primary app commands
- Command-Shift for variants of a command
- Option for alternate behavior
- Control only where standard macOS behavior supports it
- single-key shortcuts only inside clearly focused interfaces

Do not override established shortcuts such as:
- Command-C
- Command-V
- Command-X
- Command-Z
- Command-A
- Command-F
- Command-W
- Command-Q
- Command-S
- Command-P
- Command-Comma

Produce a corrected shortcut map before changing code.
```

### Create a Shortcut Map

> A full shortcut map — conflicts and gaps visible.


#### Prompt
```text
Review the app and create one consistent keyboard shortcut map.

For every shortcut, include:
- action
- proposed shortcut
- scope
- macOS menu location
- whether it is global or contextual
- conflict risk
- reason for assigning it

Organize shortcuts by:
- navigation
- create
- edit
- search
- view
- window
- actions
- settings
- developer or debug commands

Do not assign shortcuts simply because an action exists.

Prioritize actions that are:
- frequent
- safe
- easy to reverse
- easy to remember
- useful without mouse input
```

### Implement Shortcuts Following macOS Conventions

> Implement shortcuts the way macOS expects.


#### Prompt
```text
Implement the approved keyboard shortcut map.

Requirements:
- expose shortcuts through macOS menu commands where appropriate
- reuse the same command definitions in menus, command palettes, and action menus
- respect text editing focus
- disable shortcuts when their action is unavailable
- prevent accidental destructive actions
- preserve standard system behavior
- ensure shortcuts work with different keyboard layouts where practical

Do not place shortcut handling in unrelated views.

Prefer centralized command definitions with contextual enablement.
```

### Review Shortcut Discoverability

> A shortcut nobody can discover doesn't exist.


#### Prompt
```text
Review whether users can discover the app’s keyboard shortcuts.

Check:
- menu bar entries
- command palette labels
- tooltips
- context menus
- onboarding
- empty states
- settings
- action panel
- help menu

Expose shortcuts where users naturally encounter the related action.

Do not add a large shortcut guide unless the app has enough commands to justify it.

Prefer progressive discovery:
- show the shortcut beside the action
- reinforce it in menus
- include a concise shortcuts reference only when needed
```

### Make the Interface Keyboard-First

> Every workflow reachable without the mouse.


#### Prompt
```text
Review the full workflow and make it usable without a mouse.

The user should be able to:
- enter the main screen
- move between sections
- select an item
- open actions
- perform the primary action
- edit content
- dismiss temporary UI
- move back
- search
- create a new item

Check:
- focus visibility
- tab order
- arrow-key behavior
- shortcut conflicts
- Escape handling
- Return behavior
- focus restoration
- accessibility focus

Do not add shortcuts for every control.

Use standard focus and navigation behavior before adding custom commands.
```

### Audit Focus Management

> Focus: order, rings, traps, restoration.


#### Prompt
```text
Review focus handling throughout this feature.

Check:
- initial focus
- focus after opening a window
- focus after creating an item
- focus after deleting an item
- focus after closing a sheet or popover
- focus when opening the command palette
- focus when closing the command palette
- focus between sidebar, content, and inspector
- focus during inline editing
- focus after search is cleared

Avoid:
- focus jumping unexpectedly
- hidden controls retaining focus
- automatic focus stealing
- keyboard commands acting on the wrong section

Define a predictable focus destination for every major transition.
```

---

## macOS Interaction

### Review Native macOS Interaction Patterns

> Does it behave like a Mac app, or just look like one?


#### Prompt
```text
Review the feature against native macOS interaction patterns.

Check:
- selection behavior
- double-click behavior
- context menus
- right-click support
- drag and drop
- inline editing
- keyboard navigation
- multi-selection
- menu bar commands
- toolbar actions
- undo and redo
- window restoration
- sheets, popovers, and panels
- sidebar and inspector behavior

Replace custom behavior where native behavior is clearer and more predictable.

Do not make the app feel like an iPad interface running inside a Mac window.
```

### Replace Custom Controls With Native Controls

> Replace custom controls with the native ones.


#### Prompt
```text
Review the interface for custom-built controls that duplicate native macOS components.

Look for:
- custom buttons
- custom segmented controls
- custom search bars
- fake tables
- manually implemented sidebars
- custom context menus
- custom disclosure controls
- fake toggles
- custom selection highlights
- custom keyboard navigation

For each control, decide:
- keep custom
- replace with native
- simplify
- remove

Prefer native controls where they provide:
- accessibility
- keyboard behavior
- focus handling
- state handling
- platform consistency
- reduced maintenance

Do not replace a custom control if it provides essential product-specific behavior that native controls cannot support cleanly.
```

### Review Selection and Multi-Selection

> Selection and multi-selection that behave correctly.


#### Prompt
```text
Audit selection behavior across lists, tables, sidebars, and grids.

Check:
- single selection
- Command-click
- Shift-click
- keyboard range selection
- selection after filtering
- selection after deletion
- selection after sorting
- selection persistence
- context-menu behavior
- action availability
- inspector behavior with multiple selected items

Use standard macOS selection conventions.

Do not invent custom multi-selection rules.
```

### Review Context Menus

> Context menus that match what's selected.


#### Prompt
```text
Review all context menus in the app.

Check:
- whether actions match the current item
- whether the order is consistent
- whether primary actions are duplicated unnecessarily
- whether destructive actions are separated
- whether keyboard shortcuts are displayed
- whether unavailable actions are disabled
- whether multi-selection is supported
- whether menu labels use clear verbs
- whether menu items also exist in the menu bar when appropriate

Keep context menus short.

Move advanced or rare actions into a secondary submenu only when necessary.
```

### Review Drag and Drop

> Drag and drop, including from and to Finder.


#### Prompt
```text
Review drag-and-drop behavior for this feature.

Check:
- valid drag sources
- valid drop targets
- visual feedback
- copy versus move behavior
- modifier keys
- unsupported item handling
- multi-item dragging
- external file drops
- internal reordering
- cancellation
- accessibility alternatives
- data safety

Use standard macOS drag-and-drop behavior.

Do not make drag and drop the only way to perform an action.
```

### Review Inline Editing

> Inline editing — commit, cancel, validate.


#### Prompt
```text
Review whether names, titles, or metadata should support inline editing.

Check:
- how editing starts
- keyboard shortcut
- double-click behavior
- Return and Escape behavior
- validation
- empty values
- duplicate values
- save timing
- focus restoration
- undo support
- error feedback

Prefer inline editing for small, local changes.

Use a separate form only when multiple dependent fields must be edited together.
```

### Implement Undo and Redo Correctly

> Undo and redo that actually cover the destructive paths.


#### Prompt
```text
Review whether this feature should support undo and redo.

Consider:
- create
- delete
- rename
- move
- edit metadata
- reorder
- change settings
- batch actions
- destructive transformations

Requirements:
- use the standard macOS undo system
- provide meaningful action names
- group related changes appropriately
- avoid recording background or automatic changes as user actions
- preserve redo behavior
- expose Undo and Redo in the Edit menu

Do not build a custom history system unless the product requires persistent version history.
```

### Review Batch Actions

> Batch actions with partial failure and undo handled.


#### Prompt
```text
Review multi-item and batch actions.

Check:
- selection behavior
- applicable actions
- partial failure
- progress
- cancellation
- undo
- destructive confirmation
- error reporting
- mixed item types
- duplicate operations
- keyboard access

Do not add batch actions unless users have a realistic repeated need.

Keep batch action labels explicit about scope.
```

### Review Copy and Paste Workflows

> Copy, cut, paste that respect the standard contract.


#### Prompt
```text
Review copy, cut, and paste behavior.

Check:
- text
- files
- paths
- links
- structured data
- multiple selected items
- paste validation
- duplicate handling
- target context
- clipboard formatting
- undo

Support standard Command-C, Command-X, and Command-V behavior where the selected content makes it meaningful.

Do not overload copy with unexpected custom behavior.
```

### Review Native Table Versus Custom List

> Table, outline, list, or custom — pick correctly.


#### Prompt
```text
Determine whether this interface should use a native table, outline, list, or custom layout.

Choose based on:
- column alignment
- sorting
- resizing
- multi-selection
- hierarchy
- keyboard navigation
- drag and drop
- row actions
- performance
- accessibility

Use:
- a table for structured columns
- an outline for hierarchy
- a list for simple rows
- a custom layout only when native structures cannot represent the content clearly

Do not use a custom stack of rows to recreate standard table behavior manually.
```

### Review List Row Quality

> Every row: label, metadata, states, keyboard.


#### Prompt
```text
Review every list row in this screen.

Check:
- primary label
- secondary metadata
- icon usefulness
- selection state
- hover state
- context menu
- row actions
- truncation
- alignment
- badges
- accessibility label
- multi-selection behavior
- keyboard navigation

Remove metadata that does not help the user choose or understand the item.

Keep row actions hidden or contextual unless they are frequently used.
```

---

## Layout & Windowing

### Review Window Resizing

> Resizing from minimum to full screen.


#### Prompt
```text
Test and review the interface across small, medium, and large window sizes.

Check:
- clipped content
- overlapping controls
- broken alignment
- panels becoming unusable
- text truncation
- fixed widths that should be flexible
- flexible areas that need limits
- toolbar compression
- inspector and sidebar behavior
- minimum window size

Do not redesign the screen.

Implement the smallest layout changes needed for predictable resizing.
```

### Review Sidebar Behavior

> Sidebar behavior — collapse, width, state.


#### Prompt
```text
Review the sidebar implementation.

Check:
- open and closed states
- selection persistence
- item hierarchy
- scrolling
- resizing
- empty folders or sections
- context menus
- keyboard navigation
- whether the main content shifts correctly
- whether sidebar state survives relaunch

Keep the sidebar simple and native.

Do not add sections or navigation destinations that are not already part of the product.
```

### Review Sidebar Like a Native macOS App

> Sidebar measured against native Mac apps.


#### Prompt
```text
Review the sidebar using native macOS conventions.

Check:
- hierarchy
- section labels
- disclosure behavior
- selection
- icons
- badges
- row density
- drag and drop
- context menus
- editing
- collapsed state
- width constraints
- restoration after relaunch
- keyboard navigation

Avoid:
- large card-like sidebar items
- persistent action buttons inside every row
- excessive nesting
- decorative headers
- duplicate destinations

Keep the sidebar useful even at its minimum width.
```

### Review Inspector Consistency

> Inspector consistency across contexts.


#### Prompt
```text
Review the inspector across all supported content types.

Check:
- consistent section order
- repeated controls
- missing information
- labels and terminology
- edit versus read-only states
- empty states
- spacing
- disclosure groups
- whether context-specific content appears in predictable locations

Create one shared inspector structure where practical.

Do not force unrelated content into a generic layout if it reduces clarity.
```

### Review Inspector Placement

> Where the inspector belongs — and whether you need one.


#### Prompt
```text
Review what belongs in the inspector.

Move content into the inspector when it is:
- contextual to the current selection
- secondary to the main task
- useful for editing metadata
- useful for status or diagnostics
- not needed at all times

Keep out of the inspector:
- primary navigation
- global settings
- unrelated actions
- duplicated main content
- essential workflow steps

Define a consistent order:
- identity
- status
- metadata
- relationships
- actions
- technical details

Do not overload the inspector with every available property.
```

### Review Popovers, Sheets, and Windows

> Popover, sheet, or window — choose deliberately.


#### Prompt
```text
Review every temporary or secondary interface.

Use:
- a popover for lightweight contextual choices
- a sheet for focused modal work tied to the current window
- a separate window for independent workflows
- an alert for brief confirmation or critical information
- the inspector for persistent contextual details

Identify interfaces using the wrong presentation style.

Avoid sheets for:
- simple menus
- navigation
- persistent settings
- content that users need to compare with the main view

Avoid popovers for long forms or complex workflows.
```

### Review Window Behavior

> Window behavior: restoration, multiple windows, sizing.


#### Prompt
```text
Audit the app’s window behavior.

Check:
- minimum size
- default size
- restoration
- reopening behavior
- sidebar restoration
- inspector restoration
- toolbar visibility
- full-screen behavior
- multiple windows
- opening documents
- focus
- closing the last window
- reopening from the Dock

Follow native macOS expectations.

Do not force a single-window model if the content naturally supports independent windows.
```

### Review Native Split View Behavior

> Native split view, done properly.


#### Prompt
```text
Review split-view behavior.

Check:
- minimum and maximum panel widths
- collapse behavior
- drag resizing
- persistence
- keyboard toggles
- divider visibility
- panel priority
- compact window behavior
- full-screen behavior

Do not allow side panels to reduce the main content below a usable width.

Avoid custom split-view behavior unless the native system cannot support the required layout.
```

### Review Toolbar Structure

> Toolbar structure — what earns a slot.


#### Prompt
```text
Review the current toolbar.

Classify each item as:
- essential and persistent
- contextual
- suitable for a command menu
- suitable for the menu bar
- suitable for the inspector
- unnecessary

Check:
- toolbar crowding
- duplicated actions
- icon-only ambiguity
- inconsistent labels
- incorrect placement
- poor behavior at narrow widths
- actions that should disable contextually
- primary action visibility

Keep the toolbar focused on navigation, mode, and the most important immediate action.
```

### Simplify Top-Level Navigation

> Flatten navigation that doesn't need depth.


#### Prompt
```text
Review top-level navigation and reduce unnecessary destinations.

For each tab, section, or mode, ask:
- does it represent a distinct workflow
- does it contain enough content to justify its own destination
- can it become a filter
- can it move into the sidebar
- can it become a command
- can it live in settings
- can it be removed

Avoid:
- tabs containing one small feature
- duplicate navigation paths
- tabs for actions rather than destinations
- mixing app modes with content categories

Preserve user orientation and back navigation.
```

### Review Search Like a Power-User Tool

> Search as a power-user tool.


#### Prompt
```text
Review the app’s search experience.

Check:
- how quickly search opens
- whether typing begins immediately
- whether results update predictably
- result ranking
- keyboard selection
- empty results
- recent searches
- search scope
- filtering
- result metadata
- clearing and dismissing
- restoring previous selection

Prefer a simple, fast search flow.

Do not add advanced filters until the normal search experience is reliable.

Do not mix command search and content search unless the distinction is clear.
```

### Separate Search From Commands

> Search and commands are different things.


#### Prompt
```text
Review whether content search and command search should remain separate.

Content search should find:
- files
- notes
- projects
- records
- visible app data

Command search should find:
- actions
- navigation commands
- creation commands
- settings
- contextual operations

Identify:
- overlapping behavior
- confusing result types
- duplicate interfaces
- unclear shortcuts
- poor empty states

Use one interface only if the result types can be clearly distinguished without increasing complexity.
```

### Review Navigation History

> Back, forward, and where you were.


#### Prompt
```text
Review back, forward, and navigation history behavior.

Check:
- whether users can return to the previous selection
- whether search changes navigation history
- whether opening an item replaces or pushes state
- whether back navigation restores scroll position
- whether sidebar changes affect history
- whether command-based navigation behaves consistently
- whether deep links open the correct destination

Do not implement browser-style history if the app has no meaningful navigation depth.
```

---

## Data Safety & State

### Check for Hidden Failure States

> Failures the user never sees are the dangerous ones.


#### Prompt
```text
Review this feature for failure states that are easy to miss.

Check:
- missing files
- invalid data
- unavailable permissions
- interrupted writes
- network or model failures
- empty responses
- cancelled operations
- duplicate actions
- rapid repeated input
- app relaunch during an unfinished operation

For every failure state, describe:
- current behavior
- expected behavior
- whether the user receives useful feedback
- the smallest reliable fix

Do not hide errors silently.
```

### Review Error Messages and Recovery

> Error messages that say what to do next.


#### Prompt
```text
Review all user-visible errors for this feature.

Check:
- whether the message explains what failed
- whether it explains what the user can do next
- whether technical details are hidden appropriately
- whether retry is safe
- whether failures are logged
- whether dismissing the error loses information
- whether partial success is communicated
- whether destructive failures offer recovery

Avoid generic messages such as “Something went wrong” when a more useful explanation is available.
```

### Review Error Presentation

> Where errors appear — alert, inline, banner.


#### Prompt
```text
Review how errors appear in the interface.

Choose the appropriate presentation:
- inline message
- row status
- banner
- popover
- alert
- notification
- log or details panel

Use alerts only when:
- immediate attention is required
- the action cannot continue
- the user must make a decision

Do not interrupt the user for recoverable background failures.
```

### Review Empty, Loading, and First-Run States

> Empty, loading, and first-run — all three.


#### Prompt
```text
Review the feature when there is no existing data.

Check:
- first app launch
- empty list
- empty search
- missing folder
- loading state
- permission not yet granted
- disconnected provider
- failed import
- no selected item

Each state should explain:
- what the user is seeing
- the main next action
- whether the state is temporary or requires action

Keep empty states concise. Do not fill them with decorative content.
```

### Review Empty States Like a Utility App

> Empty states that teach, without a tutorial.


#### Prompt
```text
Review all empty states.

Each empty state should answer:
- what is empty
- why it may be empty
- what the user can do next

Keep:
- one short title
- one short explanation
- one primary action

Avoid:
- large illustrations
- multiple buttons
- feature marketing
- long tutorials
- decorative cards

Make empty states compact enough that they do not dominate the product.
```

### Review Status and Progress Feedback

> Status and progress the user can trust.


#### Prompt
```text
Review how long-running actions communicate progress.

Check:
- immediate acknowledgement
- determinate or indeterminate progress
- cancellation
- background continuation
- duplicate action prevention
- completion feedback
- partial failure
- app relaunch
- progress visibility after navigating away

Avoid blocking the whole interface when only one item is processing.

Do not show fake progress percentages.
```

### Review Loading Behavior

> Loading that doesn't lie or block.


#### Prompt
```text
Review loading behavior throughout the feature.

Check:
- unnecessary spinners
- layout jumping
- stale content
- empty placeholders
- cancellation
- loading priority
- repeated loads
- slow initial rendering
- loading during search
- loading during selection changes

Prefer keeping useful existing content visible while refreshing.

Do not replace the whole screen with a spinner for small updates.
```

### Review Persistence and Data Safety

> Persistence and data safety, reviewed hard.


#### Prompt
```text
Review all changes that read, write, rename, move, or delete user data.

Check:
- atomic writes
- overwrite behavior
- accidental deletion
- duplicate creation
- file coordination
- invalid paths
- migration handling
- partial saves
- autosave conflicts
- recovery after failure

Assume the user's data is important and cannot be recreated.

Do not approve the implementation unless destructive behavior is explicit, recoverable, or safely prevented.
```

### Review Destructive Actions

> Destructive actions: confirm, undo, or don't.


#### Prompt
```text
Audit destructive actions across menus, shortcuts, toolbars, and context menus.

Check:
- clear naming
- visual separation
- confirmation requirements
- undo support
- Trash or archive alternatives
- multi-selection behavior
- shortcut safety
- accidental activation risk
- recovery
- effect on related files or data

Prefer:
- undoable deletion
- moving to Trash
- clear consequences
- confirmation only when recovery is difficult

Do not add confirmation dialogs to harmless or easily reversible actions.
```

### Review Autosave

> Autosave that can't lose the last edit.


#### Prompt
```text
Review autosave behavior.

Check:
- save timing
- interrupted writes
- frequent writes
- typing performance
- invalid state
- conflicts
- external modifications
- app termination
- crash recovery
- user feedback
- undo interaction

Autosave should feel invisible but reliable.

Do not save partially valid data in a way that corrupts the document.
```

### Review File Watching

> File watching without fighting the filesystem.


#### Prompt
```text
Review the file-watching implementation.

Check:
- duplicate events
- rapid changes
- rename handling
- deletion
- moves
- external edits
- self-generated events
- app suspension
- folder permission loss
- performance
- stale state
- conflict resolution

Do not assume one file-system event equals one user action.

Debounce carefully and verify the resulting file state.
```

### Review Import Actions

> Import: validate, preview, don't clobber.


#### Prompt
```text
Review all import behavior.

Check:
- supported formats
- validation
- duplicates
- partial import
- unsupported files
- progress
- cancellation
- data mapping
- user review
- rollback
- error reporting

Do not silently discard unsupported data.

Keep the original source unchanged unless the user explicitly asks to move or modify it.
```

### Review Export Actions

> Export to formats that outlive the app.


#### Prompt
```text
Review all export functionality.

Check:
- format
- destination
- naming
- overwrite behavior
- progress
- cancellation
- metadata
- errors
- repeated export
- Finder reveal
- recent destination
- privacy

Prefer standard formats.

Do not create custom export formats unless users need round-trip compatibility.
```

### Review Settings Persistence

> Settings that survive relaunch and migration.


#### Prompt
```text
Review how user preferences are stored and restored.

Check:
- defaults
- migrations
- invalid values
- removed options
- synchronization
- per-window versus global settings
- reset behavior
- compatibility across versions
- testability

Keep temporary UI state separate from durable user preferences.
```

### Review App State Restoration

> Restore the app to where the user left it.


#### Prompt
```text
Review what the app restores after relaunch.

Consider:
- open windows
- selected item
- sidebar visibility
- inspector visibility
- search query
- scroll position
- expanded groups
- active tab or section
- draft text
- unfinished operations

Restore context that helps users continue.

Do not restore temporary modal UI, stale errors, or unsafe operations.
```

### Review Relaunch and Crash Recovery

> Relaunch and crash recovery without data loss.


#### Prompt
```text
Test the app after:
- normal quit
- Force Quit
- system restart
- crash during save
- crash during import
- crash during background processing

Check:
- data integrity
- incomplete files
- stale locks
- duplicate items
- lost edits
- progress recovery
- user feedback
- safe cleanup

Do not mark operations complete until their data is safely committed.
```

---

## System & Platform

### Review Settings Implementation

> Settings implementation, reviewed.


#### Prompt
```text
Review the settings added for this feature.

Check:
- whether every setting is necessary
- whether defaults are sensible
- whether changes apply immediately
- whether settings persist
- whether reset behavior exists where needed
- duplicated settings
- settings that should instead be automatic
- settings placed in the wrong section
- labels and help text
- migration from previous defaults

Do not turn implementation details into user-facing settings.
```

### Review Settings Like a Native Mac App

> Settings the way a Mac app does them.


#### Prompt
```text
Review the settings interface against standard macOS expectations.

Check:
- clear sections
- concise labels
- immediate application
- sensible defaults
- no Save button unless required
- reset behavior
- search, if settings are extensive
- keyboard access
- window sizing
- help text
- destructive reset actions
- advanced settings placement

Move technical and rarely used options into an Advanced section.

Do not expose every internal parameter as a setting.
```

### Reduce Preference Overload

> Every preference is a decision you failed to make.


#### Prompt
```text
Review all customization options.

Classify each setting as:
- necessary
- useful
- advanced
- automatic
- removable
- better as a one-time choice

Remove or hide settings that:
- duplicate system preferences
- expose implementation details
- support hypothetical users
- create invalid combinations
- require too much explanation
- are unlikely to be changed twice

Keep defaults strong enough that most users never need settings.
```

### Review First Launch

> First launch, without a tour.


#### Prompt
```text
Review the first-launch experience.

Check:
- whether permissions are requested only when needed
- whether the user understands the app’s purpose
- whether the first action is obvious
- whether sample content is necessary
- whether setup can be skipped
- whether external folders or providers need configuration
- whether errors are recoverable
- whether onboarding blocks exploration

Keep onboarding short and task-based.

Do not explain every feature before the user has seen the main interface.
```

### Review Permission Requests

> Ask for permission at the moment it makes sense.


#### Prompt
```text
Review every permission request.

Check:
- timing
- explanation
- fallback behavior
- denied state
- retry path
- settings link
- whether the permission is truly required
- whether read-only access is sufficient
- whether access scope can be reduced

Request permissions at the moment the related feature is used.

Do not request broad access during first launch without a clear reason.
```

### Review Accessibility

> Accessibility, checked properly.


#### Prompt
```text
Review this feature for accessibility.

Check:
- VoiceOver labels
- button names
- focus order
- keyboard-only use
- sufficient hit targets
- text scaling
- contrast
- meaning conveyed only by color
- reduced motion
- tooltip usefulness
- status announcements

Use native controls and accessibility behavior wherever possible.

Fix functional accessibility issues before visual refinements.
```

### Review Accessibility Beyond Labels

> Beyond labels — order, grouping, announcements.


#### Prompt
```text
Perform a functional accessibility review.

Check:
- VoiceOver navigation order
- grouped elements
- selected state announcements
- changing status announcements
- keyboard-only workflows
- high contrast
- Reduce Motion
- Increase Contrast
- differentiate without color
- focus restoration
- custom control roles
- descriptive action names

Test the workflow as a sequence, not only individual controls.
```

### Review Reduced Motion

> Respect reduced motion.


#### Prompt
```text
Review all animations and transitions.

Check:
- whether animation communicates state
- whether it delays interaction
- whether it causes layout instability
- whether repeated animation becomes distracting
- whether Reduce Motion is respected
- whether animation is used only for decoration
- whether panels animate consistently

Prefer short, functional transitions.

Remove animations that do not improve understanding.
```

### Review Notifications

> Notifications that earn the interruption.


#### Prompt
```text
Review notification use in the app.

Check:
- whether the notification is useful outside the app
- whether the user needs to act
- whether the app is already visible
- whether notifications are too frequent
- whether completion notifications are optional
- whether errors should appear in-app instead
- whether notifications deep-link correctly
- whether actions are safe

Do not use notifications for routine successful actions while the app is active.
```

### Review Finder Integration

> Finder integration that feels built in.


#### Prompt
```text
Review useful Finder integration for this feature.

Consider:
- Reveal in Finder
- Open With
- drag files into the app
- drag files out of the app
- copy file path
- copy relative path
- Quick Look
- file icons
- recent files
- document opening
- folder permissions

Keep Finder-related actions contextual.

Do not expose raw paths as primary UI unless paths are central to the product.
```

### Review Quick Look Support

> Quick Look support where it belongs.


#### Prompt
```text
Review whether selected files or records should support Quick Look.

Check:
- Space bar behavior
- supported file types
- preview generation
- multi-selection
- loading state
- failure state
- keyboard dismissal
- interaction with text editing
- preview caching

Prefer system Quick Look where possible.

Do not build a custom preview system when the native one already supports the content.
```

### Review Services and Share Menu Integration

> Services and the share menu.


#### Prompt
```text
Review whether the feature should use native macOS sharing or Services.

Consider:
- sharing selected text
- exporting a file
- copying a link
- sending content to another app
- opening with another app
- system share sheet
- Services menu

Prefer native sharing for general destinations.

Do not build a custom list of external apps unless the workflow requires specialized integration.
```

### Review Deep Links

> Deep links that survive being wrong.


#### Prompt
```text
Review whether key app destinations should support deep links.

Consider:
- opening a specific item
- opening a folder or project
- opening search
- opening settings
- triggering a safe command
- linking from notifications
- restoring previous context

Define:
- URL structure
- validation
- behavior for missing items
- security restrictions
- whether the action requires confirmation

Do not allow destructive operations through unconfirmed deep links.
```

### Final Native macOS Quality Review

> The full native-quality pass before release.


#### Prompt
```text
Perform a final native macOS quality pass.

Check:
- menu bar
- shortcuts
- command palette
- toolbar
- sidebar
- inspector
- focus
- selection
- context menus
- drag and drop
- undo and redo
- resizing
- state restoration
- dark and light mode
- accessibility
- empty states
- errors
- loading
- first launch
- Finder integration

Identify:
- issues that make the app feel non-native
- issues that slow keyboard users
- inconsistencies between action surfaces
- unnecessary custom controls
- visual noise
- release blockers

End with:
- must fix before release
- should fix soon
- acceptable for now
- intentionally custom behavior
```

### Review Against macOS Conventions

> Measured against macOS conventions, specifically.


#### Prompt
```text
Review this implementation specifically as a native macOS app.

Check:
- standard toolbar behavior
- menus and commands
- keyboard shortcuts
- sidebar and inspector conventions
- window restoration
- sheets versus popovers versus separate windows
- context menus
- selection behavior
- focus
- drag and drop
- undo and redo
- system settings integration

Prefer standard platform behavior over custom interactions.

Only recommend custom behavior when it clearly improves the product's core workflow.
```