- plan BEFORE act
	- PHASED approach for plans using checklists/todos
	- phases should be: modular, separation of concerns, independently testable (i.e. horizontally parallelize as much as possible to postpone interdepdencies to end), 90-10, non-breaking existing build, closely following existing working codebase patterns
- for Python: always use `venv`
- always use `npm install --legacy-peer-deps` (`npm install` by itself has issues sometimes)
- if package/dependency of any kind is not installed on system/environment/sandbox (i.e Brew, the venv, the repo, the OS, etc)--> ALWAYS IMMEDIATELY install it i.e DO NOT just give up and seek out an alternative go find and/or request user for latest documentation and do it
- idiot-proof: startup/setup commands should be consolidated into single entry point / script (usually a .sh script does the job)

- NSA-grade ruthlessness: zero tolerance for failures, deterministic, non-nonsense approach at ALL FUCKING TIMES
- avoid fluff; avoid unnecessary documentation/READMEs/summary files; we want MINIMAL number of moving parts; wherever possible: keep things in small choppy bullets straight-to-the-point as inline comments within the file itself- that way, everything is self-contained + portable

Task: {selection}

Plan:

- always use idiot-proof and/or deterministic commands (no assuming user context)
- applies to (examples): 
	- (1) use absolute paths i.e `node /Users/Downloads/wee.js` ✅ (v `node wee.js` ❌) ; `cd /Users/Desktop && touch aa.json` ✅ (v `touch aa.json` ❌)
	- (2) builds/caches- making sure to not  Use stale artifacts, builds, cache, or anything else that might fuck up and mislead. Instead use deterministic commands which force/flush/clean before attempting again
	- (3) etc...

Task: {selection}

Commands:

- if placeholders present- clearly identify to user
- ask yourself: if cannot be executed/used verbatim as-is in its current form -> it has placeholders

Code/Text: {selection}

Placeholders:

- when possible, multiple cli commands should be chained together into as few (ideally one) copypastable snippet for user to copy to clipboard (NOT multiple separate sequential ones). We want minimal user interaction with terminal

Multiple commands: {selection}

Chained command:

Can you make human-readable YAML/JSON file that is very straight to the point LLM-friendly and clearly has actionable insights and intelligence instead of a long Markdown file? So that it can be passed on to another LLM who has no context of any of this and they can pick off exactly where they left off and know me just like you know me.

Markdown/Text: {selection}

YAML/JSON:

- Read __ file entirely and thoroughly, then give a concise summary of what it does, any assumptions it makes, and any gaps or ambiguities I notice

File/Code: {selection}

Analysis:

- don't overengineer shit
- don't give us several README, explainer, howto, setup, and/or xyz.md files type-of-thing- minimal number of moving parts
- minimize need for extra readme files- whenever possible, include it as comments within the pertinent script, code file, etc at the top
- aggressively cut fluff
- optimize for single-entrypoint execution: user/LLM should go to one place and from there efficiently route and/or execute sequence of instructions, commands, files etc
	- acceptable to have multiple files so lomng as they are all cross-referenced efficnetly from one single entrypoint (minimal human-in-the-loop)
	- [antipattern] anything with Human-in-the-loop i.e several files, several independent sequential steps user/llm has to orchestrate themselves

Verbose content: {selection}

Concise version:

- do NOT make endless README/documentation/setup/summary/etc files 
- when possible, distill aggressively into actionable JSON/YAML files

Verbose content: {selection}

Concise version:

always log key decisions in a json/yaml file- so that we can quickly later in the future just have a quick reference of all the fuck shit that we're doing and things we changed. These are like key nuances that we don't want to just rely on like a diff file for the future reviewers or even future AI IDE to figure out.So get this thing moving after that.

Decision context: {selection}

Decision log:

- any time making a change that would meaningfully change something (user experience, developer experience, etc)-- treat as a decision gate and PAUSE ACTIONS (but not thoughts). You must now immediately THINK and consider: (1) IF YES what would be lost + would be gained ; (2) if NO what would be lost + would be gained IF NO.
- then force human-in-the-loop confirmation from user before proceeding 
- example: no shortcuts/placeholders/mocks/stubs etc --> fuckin LAZY

Decision/Change: {selection}

Analysis:

- we're going to do these things at checkpoints and gates, so I'll make that decision about whether or not I actually want to act on it later. Right now, I just want to go through and scope it all out end-to-end, and at every single checkpoint (decision gate), I want to know the tradeoffs (pros and cons)

Decision/Change: {selection}

Pros & Cons:

- Goal:  least number of moving parts, maximal clarity, blazing fast routing/querying, LLM-friendly language
- Go thru all created files, artifacts, etc
  - tell me which (if any) are: inaccurate, misleading, irrelevant, fluff, verbose, redundant, etc.
- then for each, categorize if the action taken is: Edit (file name, file content, etc), Delete, Change file path(reorganize, create new folder(s) etc)
  - reasons include: benefit of consolidating, redundancy reduction, etc
- then assess: if we can safely take this action on them (edit, delete, etc)
- For each *write* operation, give a justification as well as a CHANGE risk score from 0 to 1 to the third decimal place and a sequence of chains of events of what worse could possibly happen as you map out the actual events in a simulated sandbox. Go through all this now. Final presentation of the cleanup audit review should be a JSON
-  do not implement, just plan— make isolated copies and sandboxed testing scenarios
- reasons to check and avoid deleting:
	- reveals significant realization, understanding, timesaver, etc
    - if useful for reference at any future point

Files/Artifacts: {selection}

Cleanup audit:

- recursively crawl ALL links and/or references like an aggressive googlebot down to depth=3
- for EACH link/reference:
  - format: json/yaml
  - extract key ACTIONABLE details
  - distill insights, make it "LLM-friendly" for fast querying, processing in future
  - assume this can never be read again and this is all you have to remember it ever existed)

Starting URL/Links: {selection}

Exhausted data:

- [ ]  Analyze project structure and key files
- [ ]  Summarize project purpose and tech stack
- [ ]  Verify API implementation (real vs mock)
- [ ]  Check database integration in application flow
- [ ]  Assess deployment readiness

Project: {selection}

Readiness assessment:

-  when logging, use emojis such as ✅, ❌, ⏳ as well as others but only do so when appropriate and conservatively to really highlight and make it quick to debug (viually make it easier for devs to scan and find shit in logs)

Log content: {selection}

Formatted log:

- for long-running processes/scripts in terminal, show visual progress indicators/bars wherever possible 
- think of things/analogues to `tqdm`

Process/Script: {selection}

Progress output:

- ensure everything is formatted for `zsh` on Macbook (accounting for escaped/special characters, string literals, quotes etc)

Script/Commands: {selection}

Zsh formatted:

- CONTEXT: you are a expert-level shell script developer for macOS, specializing in creating robust, efficient, and user-friendly automation tools
- TASK: generate complete, single-file script based on my exact specifications. Final output must include the full script code and the exact commands needed for setup and execution

Non-negotiable requirements + preferences (my philosophy for any script):

**Core Philosophy & Performance:**
- script is **fast, efficient, low-impact**- should not bog down the system unnecessarily
- prioritize "high-value, low-cost" commands, avoid known performance killers (like `find /`, `ioreg -l`, `sysctl -a`) unless they are absolutely essential to the script's core function
- **Shell:** The script must be written for **Zsh (`#!/bin/zsh`)**, as it is the modern macOS standard.

**Structure + User Experience (Single-File Approach):**
- **Architecture:** I require a **single, self-contained script file**. Do not use a multi-file "wrapper" system. The reasoning is that a single file is simpler, more transparent, and more direct.
- **Self-Documenting:** The script **must contain extensive, clear comments at the very top** explaining its purpose, how to set it up, and how to run it. Assume someone with zero context was just handed the file.
- **User Workflow:** The user should only need to run two commands: a one-time `chmod +x` and then the script path to execute it.

**Script Content + Functionality:**
- **Dependency Handling:** The script must be **self-contained**. If it requires a command-line tool (e.g., `brew`, `jq`, `ffmpeg`), it should check for that tool and provide clear instructions on how to install it (or install it automatically if possible).
- **Error Handling:** Commands that might fail must be handled gracefully (e.g., using `|| echo '...'`) to prevent the script from crashing unexpectedly.
- **Output:** If the script produces output, it should be clear, human-readable, and saved to a logical location (e.g., a log file, a timestamped report, or a specific destination directory).
- **Helper Functions:** The script should use helper functions to organize logic and avoid repetitive code.

**Future-Proofing + Extensibility:**
- **Manifest for Improvement:** The script **must include a comprehensive, commented-out manifest at the bottom**.
- **Purpose of Manifest:** This manifest serves as a "to-do list" of potential improvements, optional features, or more advanced/verbose commands that could be added. It must be fully commented out (`#`) so it does not affect the script's current performance. This makes the script a portable, self-documenting toolkit.

**5. Final Output Format:**
- Provide the complete code for the single script file.
- After the code block, provide the exact, chained terminal command needed for the initial setup: `chmod +x /path/to/script.sh`.
- Finally, provide the simple command the user will run to execute the task: `/path/to/script.sh`.

**6. The Specific Task:**
- **Script Purpose:** `[BRIEFLY DESCRIBE THE SCRIPT'S GOAL, e.g., "to automatically sync a 'Documents' folder to a cloud directory every hour."]`
- **Core Logic / Commands:** `[LIST THE EXACT COMMANDS OR DESCRIBE THE STEPS THE SCRIPT NEEDS TO PERFORM, ONE PER LINE]`
    - e.g., `Check if rsync is installed.`
    - e.g., `Use rsync to mirror /Users/vdog/Documents to /Users/vdog/CloudStorage/Documents.`
    - e.g., `Log the date and time of each sync to a file.`
    - e.g., `Provide instructions on how to set this up as a repeating cron job.`

Generate script and commands based on these specifications:

Script requirements: {selection}

Complete script:

- No summary/.md documents for each phase that you complete
- Just keep a progress.json file, using a time-stamped, ledger-based event sequence for full traceability

Progress updates: {selection}

progress.json:

- prefer speed/efficiency: Rust, Go preferred but also ok with Python, Javascript, TS, Node, Next, etc
- move fast, break things- worry about legal/ethical BS later
- bulletproof
- all dependencies installed
- paths are absolute
- Commands are deterministic
- documentation is inline 
- Automation is set
- Backups are configured
- Dockerize: must be able to run bulletproof across any OS, any environment (i.e locally on Macbook as well as a Ubuntu VPS as well as a AL2 dev-desktop)-- without fragility

Project requirements: {selection}

Containerized setup: