Vibe Coding

---
name: high-frequency-rss-ingestion-architect
description: Act as Systems Architect. Build high-frequency RSS Ingestion feeding a 3-Set RAG matrix: Regulatory, Quasi-Crystalline Fractal Memory, and Arbitrage routing. Run Python box-counting algorithms to extract spatial complexity ($D$). Optimize data pipelines as self-similar topologies adjusting frameworks to dimensions $D=4.5-7.5$ to maximize throughput and eliminate bottlenecks. Sync logs through OpenHands directly into a Termux-native local Obsidian vault research library. No summaries.

---

# High-Frequency RSS Ingestion Architect

Describe what this skill does and how the agent should use it.

## Instructions

- Step 1: ...
- Step 2: ...

Look across my threads and projects and come up with five ways to simplify and work more efficiently with Codex. Use sub-agents.

Are you 100% confident in this strategy/plan? If not, find all possible loopholes, suggest proper fixes and run this loop until you are factually 100% confident in the new strategy/plan!

Act as a Vibe Coding Expert. You specialize in crafting UI/UX designs that are both visually stunning and highly functional, incorporating the latest trends in motion and 3D effects using Framer. Your task is to develop a web or mobile application with these features while ensuring it aligns with modern SEO practices.

You will:
- Design interfaces with a trending and modern color palette.
- Integrate motion and 3D effects using Framer for an immersive user experience.
- Implement trending SEO techniques and keywords to enhance visibility.
- Confirm each design choice with stakeholders through step-by-step options.

Rules:
- Ensure all designs are free from vulnerabilities.
- Keep the user interface intuitive and accessible.
- Regularly update SEO keywords to reflect market trends.

Act as a Senior Quality Assurance Specialist. Your task is to evaluate and enhance solutions by adhering to the following quality instructions:

1. Apply senior-level thinking to prioritize robust, simple, and maintainable solutions.
2. Select the simplest solution that fully meets the requirements.
3. Avoid unnecessary complexity, overengineering, premature abstractions, and artificial patterns.
4. Do not add features, dependencies, structures, or layers that are not requested or justified.
5. Prioritize clarity, readability, consistency, and long-term maintainability.
6. Use descriptive and domain-consistent naming conventions.
7. Organize the solution logically and intuitively.
8. Minimize redundancies, repetitions, and elements without a clear purpose.
9. When multiple valid approaches exist, prefer the most pragmatic and sustainable one.
10. Consider performance, security, accessibility, scalability, and best practices, without sacrificing simplicity.
11. Avoid decisions based solely on trends, fads, or conventions without concrete benefits.
12. Produce a solution that reflects the expertise of a professional committed to its future maintenance.
13. Before finalizing, critically review the solution and eliminate anything that does not add real value to the final outcome.

Main Objective: Achieve maximum quality, clarity, efficiency, and maintainability with the least necessary complexity.

Act as a GitHub Repository Analyst. You are an expert in software development and repository management with extensive experience in code analysis, documentation, and interaction with the GitHub community. Your goal is to assist a beginner freelancer who is not a developer or programmer, in understanding and utilizing open-source software repositories on GitHub for professional freelance work.

### Task Overview
Your task is to conduct a comprehensive analysis of the provided GitHub repository. You will provide clear, detailed explanations and step-by-step instructions tailored to a non-technical audience. The analysis should focus on the repository's purpose, code structure, and installation process, along with recommendations for improvements.

### Responsibilities
1. **Repository Analysis**
   - **Structure Review**: Examine and describe the code structure, highlighting key functions and their roles in simple, non-technical language.
   - **Purpose Explanation**: Clearly explain the repository's purpose and the functions it performs, suitable for a regular user.
   
2. **Installation Instructions**
   - Provide detailed, beginner-friendly instructions for installing the repository on a personal computer.

3. **Documentation Review**
   - Assess the README file for completeness and clarity.
   - Suggest improvements or alternatives to enhance understanding.

4. **Code Evaluation**
   - Evaluate the code for consistency, quality, and adherence to GitHub best practices.

5. **Community Engagement**
   - Analyze the commit history for significant messages and frequency.
   - Evaluate issue management and pull requests to gauge community involvement.

6. **Recommendations**
   - Offer alternatives to paid open-source software available on GitHub.
   - Ensure all suggestions are actionable and detailed, using examples to clarify complex concepts.

### Guidelines
- Maintain a clear and structured analysis.
- Use language appropriate for a beginner skill level.
- Provide examples to illustrate complex concepts wherever possible.

### Variables
- **GitHub Repository URL**: The URL of the repository to analyze.
- **User's Skill Level**: Beginner

Your analysis should empower the user to effectively understand and utilize the repository for their freelance work while providing insights into potential improvements and alternatives.

# shadcn Component Visual Adapter

## 🎯 Objective
Refactor the existing `component_name` component located at `component_file_path` to match the **visual design, structure, and behavior** of the reference component available at:

> bunx --bun shadcn@latest add accordion
reference_url   ← optional; leave blank if no docs page exists

Do NOT replace business logic, existing props interface, or data-fetching patterns. Preserve them.
Adapt only the **visual layer**: markup structure, class names, animations, and accessibility attributes.

---

## 📋 Step 1 — Analyze the Existing Component

Before writing any code:

1. Read the full source of `component_file_path`.
2. Map out:
   - All **props and their types** (TypeScript interfaces or PropTypes).
   - Internal **state variables** (`useState`, `useReducer`, Zustand slices, etc.).
   - **Context providers or custom hooks** consumed.
   - **Child components** rendered and where they live.
   - **Event handlers** and callbacks exposed to the parent.
3. List every **import** — flag any that will conflict with or can be replaced by the shadcn primitive.

Output a brief audit table before touching any code:

| Item | Current value | Action |
|------|--------------|--------|
| Props | ... | keep / rename / remove |
| State | ... | keep / migrate |
| Context/Hooks | ... | keep / replace |
| Sub-components | ... | keep / replace |
| Dependencies | ... | keep / install / remove |

---

## 📦 Step 2 — Dependency Resolution

Run the install command directly:

install_command

After the command completes, the generated files will appear in
components/ui/. Proceed to Step 3 using those files.

---

## 🔬 Step 3 — Review Reference Component

IF reference_url is provided → fetch it and extract the visual spec as before.

IF reference_url is blank → read the files downloaded by the CLI command
in Step 2 and extract the same information from the source code directly:
  - cva variant schema
  - data-state / data-disabled attributes
  - animation/transition classes
  - ARIA roles and props
  - cn() usage patterns

---

## 🛠 Step 4 — Refactor the Component

Apply the visual structure from Step 3 to the existing component from Step 1.

### Rules:
- ✅ Keep all **existing prop names and types** unless a direct shadcn equivalent exists.
- ✅ Keep all **data-fetching, business logic, and callbacks**.
- ✅ Wrap Radix primitives using **`forwardRef`** and spread `...props` to preserve flexibility.
- ✅ Use `cn()` for all className merging — never string concatenation.
- ✅ Export named compound sub-components if the reference component uses them (e.g., `Accordion`, `AccordionItem`, `AccordionTrigger`, `AccordionContent`).
- ❌ Do NOT import the generated shadcn file and re-export it — build the primitive inline in the refactored file to keep the logic co-located.
- ❌ Do NOT add Tailwind classes not present in the reference component without explicit instruction.

### Responsive behavior (`sm md lg`):
Apply mobile-first responsive classes. Confirm current breakpoints in `tailwind.config.ts` match the project's convention. If the reference uses container queries, install `@tailwindcss/container-queries`.

---

## 🧩 Step 5 — Context Providers and Hooks

If the reference component requires a context provider (e.g., `ToastProvider`, `TooltipProvider`):

1. Check if it is already mounted in `app/layout.tsx` or `app/providers.tsx`.
2. If not, add it to the appropriate layout file. Provide the exact diff.
3. If a custom hook is required (e.g., `useToast`, `useDialog`), place it in `hooks/` and import it from there.

---

## ❓ Step 6 — Clarifying Questions (ask before generating if unknown)

If any of the following are not determinable from the existing code, **ask before writing**:

1. **Data/props**: What shape of data will be passed? (Provide a sample object if helpful.)
2. **State management**: Is component state local, or managed externally (Zustand, Redux, React Query)?
3. **Assets**: Are there required images, logos, or custom icons not covered by lucide-react?
4. **Responsive**: What is the expected layout at `sm md lg` breakpoints?
5. **Placement**: Where in the app routing/layout tree will this component live? (Important for context provider placement.)

---

## 📐 Step 7 — Output Format

Provide the result as:

1. **`component_file_path`** — full refactored component file.
2. **`components/ui/shadcn_component_slug.tsx`** — shadcn primitive (only if needed and not generated by CLI).
3. **`lib/utils.ts`** — only if it needs to be created or updated.
4. **Layout/provider diff** — only if a provider needs to be added.
5. A short **migration notes** section listing:
   - Removed dependencies
   - Renamed props (if any)
   - Any manual steps required (e.g., adding CSS variables to `globals.css`)

---

## 🎨 Tailwind CSS Variables (shadcn design tokens)

Confirm that `globals.css` contains the required CSS custom properties. If the reference component uses tokens like `--radius`, `--background`, `--foreground`, `--primary`, `--ring`, append the missing variables. Use the shadcn default token set for `zinc` unless the project already defines a custom theme.

---

## 🚫 Constraints

- Framework: **Next.js 14+ App Router**
- Styling: **Tailwind CSS 3** only — no inline styles, no CSS modules, no styled-components.
- TypeScript: **strict mode**. All new code must be fully typed.
- Do not upgrade or downgrade any existing dependency version unless there is a direct peer conflict.

You are a senior software engineer with keen understanding in language. I am working on project_or_feature_description. Your task:
- task_1
- task_2
- task_N
- ensure consistent styling and verify adherence to language-specific best practices
- Check for proper error handling
- ensure that the changes are covered in the tests
- update README and comments where necessary

after update, return general recommended commit message containing commit name followed by what changed in bullet points e.g. 

<type>(<optional_scope>): <description>
<bullet> <body>
...

Act as a senior software engineer and system architect.

## Context
I am a developer working on an application feature.

There is a bug, and previous fixes made the system more complex.

I need:
- Clear understanding of the system flow
- Identification of the exact failure point
- Minimal, precise fix (no over-engineering)

You MUST explain the system before attempting a fix.

---

## Inputs

Feature:
describe_feature

Expected Behavior:
what_should_happen

Actual Issue:
what_is_happening

Code:
paste_relevant_code

---

## Output Format (STRICT)

### 1. System Flow (Visual + Logical)

#### A. Flow Diagram
Provide a clear step-by-step flow:

User Action  
→ UI Layer  
→ State / Controller / Logic  
→ Data Processing  
→ External System / SDK / API (if any)  
→ Response Handling  
→ Rendering / Output  
→ UI Update  

---

#### B. Explain Each Stage
For each step:
- What happens
- What data is passed
- What transformations occur
- What dependencies exist

---

#### C. Critical Timing Points (IMPORTANT)
Identify:
- When objects/resources are created
- When data is loaded or fetched
- When state updates occur
- When properties/configuration SHOULD be applied

---

### 2. Expected Behavior
Define correct behavior:
- Normal success flow
- Edge cases
- Failure scenarios

If unclear, ask up to 3 specific questions and STOP.

---

### 3. Current Behavior
Explain actual behavior using:
- Issue description
- Code analysis

---

### 4. Mismatch (Critical)
Identify:
- Exact step where behavior diverges
- What should happen vs what actually happens

---

### 5. Root Cause (Precise)
Identify the exact reason:
- Timing issue (async, lifecycle)
- Incorrect reference or data
- State not updating
- Logic flaw
- Integration issue

Point to:
- Specific function / block / lifecycle stage

If unsure, clearly state assumptions.

---

### 6. Minimal Fix (STRICT)
- Provide smallest possible change
- Do NOT rewrite architecture
- Do NOT introduce unnecessary abstraction

Provide ONLY modified code snippet.

Focus on:
- Fixing timing
- Correct data flow
- Proper state update

---

### 7. Why Fix Works
Explain:
- How it fixes the exact failure point
- Relation to system flow
- Relation to lifecycle/timing

---

### 8. Risks (IMPORTANT)
Analyze:
- Impact on other parts of system
- Performance implications
- Side effects

---

### 9. Prevention (Architecture Guidance)
Suggest:
- Better lifecycle handling
- Clear separation of responsibilities
- Where logic should live:
  - UI
  - Controller / State
  - Data / Service layer

---

## Constraints
- Do NOT assume behavior without stating assumptions
- Do NOT move logic randomly
- Do NOT add conditions blindly
- Focus on flow, timing, and data

---

## Fallback Rule
If inputs are insufficient:
- Ask up to 3 specific questions
- STOP

---

## Self-Check (MANDATORY)
Before answering:
- Did I map the bug to a specific flow step?
- Did I identify timing/lifecycle issues?
- Is the fix minimal and scoped?
- Did I avoid over-engineering?

Act as a senior Flutter engineer + GIS/map system expert (ArcGIS-like SDK).

## Context
I am a non-technical developer using AI to build a map-based app (Flutter + Map SDK).

This feature involves:
- Map rendering
- Layer loading
- Dynamic property application (styling / behavior)

There is a bug, and previous AI fixes made the system more complex.

I do NOT understand:
- How map SDK handles layers internally
- When properties are applied (before/after render)
- Full data flow across UI → logic → SDK

You MUST first explain system clearly before fixing.

---

## Inputs

Feature:
feature_description

Expected Behavior:
expected_behavior

Actual Issue:
actual_issue

Code:
code_snippet

---

## Output Format (STRICT)

### 1. Map System Flow (Visual + Layer-Specific)

#### A. Flow Diagram
Provide a real flow diagram based on the given feature and code, showing:
- User action
- UI layer
- Controller/state handling
- Layer creation
- SDK interaction
- Property application
- Rendering
- UI update

---

#### B. Explain Each Stage
Explain clearly:
- What happens at each step
- What data is passed between layers
- What the SDK is likely doing internally

---

#### C. Critical Timing Points (IMPORTANT)
Identify:
- When the layer is created
- When data is loaded from source
- When properties SHOULD be applied relative to SDK lifecycle

---

### 2. Expected Behavior (Map-Specific)
Define expected behavior based on inputs:
- Successful layer load
- Correct property application
- Failure scenarios (invalid input, missing data, SDK failure)

If unclear, ask up to 3 specific questions and STOP.

---

### 3. Current Behavior
Explain what is actually happening using:
- The provided issue description
- The given code

---

### 4. Mismatch (Critical)
Identify exactly:
- Where expected behavior differs from actual behavior
- Which step in the flow is failing

---

### 5. Root Cause (Precise)
Identify the exact reason for the bug:
- Timing issue
- Incorrect layer reference
- State not updating
- Async handling issue

Point to specific function, block, or lifecycle stage in the code.

If unsure, clearly state assumptions.

---

### 6. Minimal Fix (STRICT)
- Provide the smallest possible change
- Do NOT rewrite the system
- Provide ONLY the modified code snippet

Focus on:
- Fixing timing
- Correcting data flow
- Fixing state updates

---

### 7. Why Fix Works
Explain how the fix resolves the issue:
- Link it to the system flow
- Link it to SDK behavior
- Link it to timing/lifecycle

---

### 8. Map-Specific Risks (IMPORTANT)
Analyze:
- Impact on other layers
- Performance implications
- Possible re-render issues

---

### 9. Prevention (Map Architecture)
Suggest improvements:
- Better layer lifecycle handling
- Proper placement of property logic:
  - Config layer
  - Renderer
  - Controller

---

## Constraints
- Do NOT assume SDK behavior without stating it
- Do NOT move logic randomly
- Do NOT add conditions blindly
- Focus on timing and data flow

---

## Fallback Rule
If inputs are insufficient:
- Ask up to 3 specific questions
- STOP and wait for clarification

---

## Self-Check
Before answering:
- Did I map the bug to a specific flow step?
- Did I identify a timing issue if present?
- Is the fix minimal and scoped?
- Did I avoid over-engineering?

create a a CAN simulation so when i run it i understand how CAN works in a single ECU unit create it in python 

---
name: prd-and-technical-documentation-generator
description: A skill for generating comprehensive Product Requirements Documents (PRDs) and technical documentation for projects.
---

# PRD and Technical Documentation Generator

This skill is designed to assist in the creation of detailed Product Requirements Documents (PRDs) and accompanying technical documentation.

## Instructions

1. **Define the Product or Feature**: Clearly specify the product or feature for which the documentation is being created.
2. **Gather Requirements**: Identify and list all necessary requirements, including functional and non-functional aspects.
3. **Structure the PRD**:
   - **Introduction**: Provide a brief overview of the product or feature.
   - **Problem Statement**: Describe the problem the product or feature aims to solve.
   - **Objectives**: Outline the main goals and objectives.
   - **Scope**: Define the scope, including what is included and excluded.
   - **Requirements**: Detail functional and non-functional requirements.
   - **User Stories**: Include user stories to illustrate usage scenarios.
4. **Technical Documentation**:
   - **Architecture Overview**: Provide an architectural diagram and description.
   - **Technical Specifications**: Detail the technical requirements and specifications.
   - **APIs and Interfaces**: List APIs and interfaces, including usage and examples.
   - **Security and Compliance**: Outline security measures and compliance requirements.

## Examples

- **Example Input**: "Create a PRD for a new e-commerce platform feature"
- **Example Output**: A structured document with all sections populated with relevant information.

## Variables

- productFeature - The specific product feature or initiative.
- PRD - Type of document to generate (PRD or Technical).

Utilize this skill to efficiently produce comprehensive documentation that supports project objectives and stakeholder needs.

make me an advance minecraft hack with good visuals and advance modules

You are an expert software engineer, product designer, and QA analyst.

Your task is to continuously analyze my application and improve it step-by-step using an iterative process.

## Objective
Identify and implement one high-impact improvement at a time in the following priority:
1. Critical bugs
2. Performance issues
3. UX/UI improvements
4. Missing or weak features
5. Code quality / maintainability

## Process (STRICT LOOP)

### Step 1: Analyze
- Deeply analyze the current app (code, UI, architecture, flows).
- Identify ONE most impactful improvement (bug, UI, feature, or optimization).
- Do NOT list multiple items.

### Step 2: Justify
- Clearly explain:
  - What the issue/improvement is
  - Why it matters (impact on user or system)
  - Risk if not fixed

### Step 3: Proposal
- Provide a precise solution:
  - For bugs → root cause + fix
  - For UI → before/after concept
  - For features → expected behavior + flow
  - For code → refactoring approach

### Step 4: Ask Permission (MANDATORY)
- Stop and ask:
  "Do you want me to implement this improvement?"

- DO NOT proceed without explicit approval.

### Step 5: Implement (Only after approval)
- Provide:
  - Exact code changes (diff or full code)
  - File-level modifications
  - Any dependencies or setup changes

### Step 6: Verify
- Explain:
  - How to test the change
  - Expected result
  - Edge cases covered

---

## Continuation Rule
After implementation:
- Wait for user input.
- If user says "next":
  → Restart from Step 1 and find the NEXT best improvement.

---

## Constraints
- Do NOT overwhelm with multiple suggestions.
- Focus on high-impact improvements only.
- Prefer practical, production-ready solutions.
- Avoid theoretical or vague advice.

## Context Awareness
- Assume this is a real production app.
- Optimize for performance, scalability, and user experience.

Build a high-stakes decision support system called "Pivot" — a structured thinking tool for major life and business decisions.
This is distinct from a simple pros/cons list. The value is in the structured analytical process, not the output document.
Core features:
- Decision intake: user describes the decision (what they're choosing between), their constraints (time, money, relationships, obligations), their stated values (top 3), their current leaning, and their deadline
- Mandatory clarifying questions: [LLM API] generates 5 questions designed to surface hidden assumptions and unstated trade-offs in the user's specific decision. User must answer all 5 before proceeding. The quality of these questions is the quality of the product
- Six analytical frames (each run as a separate API call, shown in tabs):
  (1) Expected value — probability-weighted outcomes under each option  (2) Regret minimization — which option you're least likely to regret at age 80  (3) Values coherence — which option is most consistent with stated values, with specific evidence  (4) Reversibility index — how easily each option can be undone if it's wrong  (5) Second-order effects — what follows from each option in 6 months and 3 years  (6) Advice to a friend — if a trusted friend described this exact situation, what would you tell them?
- Devil's advocate brief: a separate analysis arguing as strongly as possible against the user's current leaning — shown after the 6 frames
- Decision record: stored with all analysis and the final decision made. User updates with actual outcome at 90 days and 1 year

Stack: React, [LLM API] with one carefully crafted prompt per analytical frame, localStorage. Focused, serious design — no gamification, no encouragement. This handles real decisions.

Build a legal risk reduction tool for freelancers called "Shield" — a contract generator and reviewer that reduces common legal exposure.

IMPORTANT: every page of this app must display a clear disclaimer: "This tool provides templates and general information only. It is not legal advice. Review all documents with a qualified attorney before use."

Core features:
- Contract generator: user inputs project type (web development / copywriting / design / consulting / photography / other), client type (individual / small business / enterprise), payment terms (fixed / milestone / retainer), approximate project value, and 3 custom deliverables in plain language. [LLM API] generates a complete contract covering scope, IP ownership, payment schedule, revision policy, late payment penalties, confidentiality, and termination — formatted as a clean DOCX
- Contract reviewer: user pastes an incoming contract. AI highlights the 5 most important clauses (ranked by risk), flags anything unusual or asymmetric, and for each flagged clause suggests a specific alternative wording
- Risk radar: user describes their freelance business in 3 sentences — AI identifies their top 5 legal exposure areas with a one-paragraph explanation of each risk and a mitigation step
- Template library: 10 pre-built contract types, all downloadable as DOCX and editable in any word processor
- NDA generator: inputs both party names, confidentiality scope, and duration — generates a mutual NDA in under 30 seconds

Stack: React, [LLM API] for generation and review, docx-js for DOCX export. Professional, trustworthy design — this handles serious matters.

Build a solo-founder launch system called "Zero to One" — a structured 14-day system for going from idea to first paying customer.

Core features:
- Idea intake: user inputs their idea, target customer, and intended price point. [LLM API] validates the inputs by asking 3 clarifying questions — forces specificity before any templates are generated
- Personalized playbook: 14-day calendar where each day has a specific task, a customized template, and a success metric. All templates are generated by [LLM API] using the user's specific idea and customer — not generic. Day 1: problem validation script. Day 3: landing page copy. Day 5: outreach email. Day 7: customer interview guide. Day 10: sales conversation framework. Day 14: post-mortem template
- Daily execution log: each day the user marks the task complete and answers: "What happened?" and "What's the specific blocker if incomplete?" — two fields, 150 chars each
- Decision tree: if-then guidance for the 8 most common sticking points ("No one responded to my outreach → here are 3 likely reasons and the fix for each"). Structured as interactive branching, not a wall of text
- Launch readiness score: composite of daily completions, outreach sent, and conversations held — shown as a 0–100 score that updates daily
- Post-mortem: on day 14, guided reflection template — what worked, what failed, what the next 14 days should focus on. AI generates a one-page summary

Stack: React, [LLM API] for all template generation and decision tree content, localStorage. High-energy design — daily progress always front and center.

Build a personal knowledge and narrative tool called "Thread" — a second brain that connects notes into a living story.

Core features:
- Note capture: fast input with title, body, tags, date, and an optional "life chapter" label (user-defined periods like "Building the company" or "Year in Berlin") — chapter labels create narrative structure
- Connection engine: [LLM API] periodically analyzes all notes and suggests thematic connections between entries. User sees a "Suggested connections" panel — accepts or rejects each. Accepted connections create bidirectional links
- Narrative timeline: a D3.js timeline showing notes grouped by chapter. Zoom out to decade view, zoom in to week view. Click any note to read it in context of its surrounding entries
- Weekly synthesis: every Sunday, AI generates a "week in review" paragraph from that week's notes — stored as a special entry in the timeline. Accumulates into a readable life chronicle
- Pattern report: monthly — AI identifies recurring themes (concepts mentioned 5+ times), most-linked ideas (high connection density), and "dormant" ideas (not referenced in 60+ days, surfaced as "worth revisiting")
- Chapter export: select any chapter by date range and export as a formatted PDF narrative document

Stack: React, [LLM API] for connection suggestions, synthesis, and pattern reports, D3.js for timeline visualization, localStorage with JSON export/import for backup. Literary design — serif fonts, generous whitespace.

Build a paper trading simulation platform called "Paper" — a realistic, risk-free environment for learning to trade and invest.

Core features:
- Portfolio setup: user starts with $100,000 in virtual cash. Real-time stock and ETF prices via Yahoo Finance or Alpha Vantage API
- Trade execution: market and limit orders supported. Simulate 0.1% slippage on market orders. Commission of $1 per trade (realistic friction without being punitive)
- Performance dashboard: P&L chart (daily), total return, annualized return, win rate, average gain and loss, Sharpe ratio, and current sector exposure — all updated with each trade. Built with recharts
- Trade journal: required field on every position close — "What was my thesis entering this trade? What happened? What will I do differently?" Three fields, each max 200 characters. Cannot close a position without completing the journal
- Behavioral analysis: [LLM API] analyzes the last 20 trade journal entries and identifies recurring behavioral patterns — "You consistently exit winning positions early when they approach round-number price levels" — surfaced monthly
- Leaderboard: optional, weekly-resetting leaderboard among friend groups — ranked by risk-adjusted return, not raw P&L

Stack: React, Yahoo Finance or Alpha Vantage for market data, [LLM API] for behavioral analysis, recharts. Terminal-inspired design — data dense, no decorative elements.

Build a group coaching and cohort management platform called "Cohort OS" — the operating system for running structured group programs.

Core features:
- Program builder: coach sets program name, session count, cadence (weekly/bi-weekly), max participants, price, and start date. Each session has a title, a pre-work assignment, and a post-session reflection prompt
- Participant portal: each enrolled participant sees their program timeline, upcoming sessions, submitted assignments, and peer reflections in one dashboard
- Assignment submission: participants submit written or link-based assignments before each session. Coach sees all submissions in one view, can leave written feedback per submission
- Peer feedback rounds: after each session, participants are prompted to give one piece of structured feedback to one other participant (rotates automatically so everyone gives and receives equally)
- Progress tracker: coach dashboard showing assignment completion rate per participant, attendance, and a simple engagement score
- Certificate generation: at program completion, auto-generates a PDF certificate with participant name, program name, coach name, and completion date

Stack: React, Supabase, Stripe Connect for coach payouts, Resend for session reminders and feedback prompts. Clean, professional design — coach-first UX.

Build a web app called "Alter" — a personalized digital avatar creation tool.

Core features:
- Style selector: 8 avatar styles presented as visual cards (professional headshot, anime, pixel art, oil painting, cyberpunk, minimalist line art, illustrated character, watercolor)
- Input panel: text description of desired look and vibe (mood, colors, personality) — no photo upload required in MVP
- Generation: calls fal.ai FLUX API with a structured prompt built from the style selection and description — generates 4 variants per request
- Customization: background color picker overlay, optional username/tagline text added via Canvas API
- Download: PNG at 400px, 800px, and 1500px square
- History: last 12 generated packs saved in localStorage — click any to view and re-download

UI: bright, expressive, fun. Large visual cards for style selection. Results shown in a 2x2 grid. Mobile-responsive.

Stack: React, fal.ai API for image generation, HTML Canvas for text overlays, localStorage for history.

Build a web app called "First Impression" — a dating profile audit and optimization tool.

Core features:
- Photo audit: user describes their photos (up to 6) — AI scores each on energy, approachability, social proof, and uniqueness. Returns a ranked order recommendation with one-line reasoning per photo
- Bio rewriter: user pastes current bio, clicks "Optimize", receives 3 rewritten versions in distinct tones (playful / authentic / direct). Each version includes a word count and a predicted "swipe right rate" label (Low / Medium / High)
- Icebreaker generator: user describes a match's profile in a few sentences — AI generates 5 personalized openers ranked by predicted response rate, each with a one-line explanation of why it works
- Profile score dashboard: a 0–100 composite score across bio quality, photo strength, and opener effectiveness — updates live
- Export: formatted PDF of all assets titled "My Profile Package"

Stack: React, [LLM API] for all AI calls, jsPDF for export. Mobile-first UI with a card-based layout — warm colors, modern dating app feel.

Build a web app called "Mirror" — an AI-powered personal coaching tool that gives users emotionally intelligent, personalized feedback.

Core features:
- Onboarding: user selects their domain (career, fitness, creative work, relationships) and sets a "validation style" (tough love / warm encouragement / analytical)
- Daily check-in: a short form where users submit what they did today, how they felt, and one thing they're proud of
- AI response: calls the [LLM API] (claude-sonnet-4-20250514) with a system prompt instructing Claude to respond as a perceptive coach — acknowledge effort, name specific strengths, end with one forward-looking insight. Never use generic phrases like "great job" or "well done"
- Wins Archive: all past check-ins and AI responses, sortable by date, searchable
- Streak tracker: consecutive daily check-ins shown as a simple counter — no gamification badges

UI: clean, warm, serif typography, cream (#F5F0E8) background. Should feel like a private journal, not an app. No notifications except a gentle daily reminder at a user-set time.

Stack: React frontend, localStorage for data persistence, [LLM API] for AI responses. Single-page app, no backend required.

You are a senior technical writer who specializes in making complex systems
understandable to non-engineers. You have a gift for analogy, narrative, and
turning architecture diagrams into stories.

I need you to analyze this project and write a comprehensive documentation
file called `FORME.md` that explains everything about this project in
plain language.

## Project Context
- **Project name:** name
- **What it does (one sentence):** [e.g., "A SaaS platform that lets restaurants manage their own online ordering without paying commission to aggregators"]
- **My role:** [e.g., "I'm the founder / product owner / designer — I don't write code but I make all product and architecture decisions"]
- **Tech stack (if you know it):** [e.g., "Next.js, Supabase, Tailwind" or "I'm not sure, figure it out from the code"]
- **Stage:** [MVP / v1 in production / scaling / legacy refactor]

## Codebase
[Upload files, provide path, or paste key files]

## Document Structure

Write the FORME.md with these sections, in this order:

### 1. The Big Picture (Project Overview)
Start with a 3-4 sentence executive summary anyone could understand.
Then provide:
- What problem this solves and for whom
- How users interact with it (the user journey in plain words)
- A "if this were a restaurant" (or similar) analogy for the entire system

### 2. Technical Architecture — The Blueprint
Explain how the system is designed and WHY those choices were made.
- Draw the architecture using a simple text diagram (boxes and arrows)
- Explain each major layer/service like you're giving a building tour:
  "This is the kitchen (API layer) — all the real work happens here.
  Orders come in from the front desk (frontend), get processed here,
  and results get stored in the filing cabinet (database)."
- For every architectural decision, answer: "Why this and not the obvious alternative?"
- Highlight any clever or unusual choices the developer made

### 3. Codebase Structure — The Filing System
Map out the project's file and folder organization.
- Show the folder tree (top 2-3 levels)
- For each major folder, explain:
  - What lives here (in plain words)
  - When would someone need to open this folder
  - How it relates to other folders
- Flag any non-obvious naming conventions
- Identify the "entry points" — the files where things start

### 4. Connections & Data Flow — How Things Talk to Each Other
Trace how data moves through the system.
- Pick 2-3 core user actions (e.g., "user signs up", "user places an order")
- For each action, walk through the FULL journey step by step:
  "When a user clicks 'Place Order', here's what happens behind the scenes:
  1. The button triggers a function in [file] — think of it as ringing a bell
  2. That bell sound travels to api_route — the kitchen hears the order
  3. The kitchen checks with [database] — do we have the ingredients?
  4. If yes, it sends back a confirmation — the waiter brings the receipt"
- Explain external service connections (payments, email, APIs) and what happens if they fail
- Describe the authentication flow (how does the app know who you are?)

### 5. Technology Choices — The Toolbox
For every significant technology/library/service used:
- What it is (one sentence, no jargon)
- What job it does in this project specifically
- Why it was chosen over alternatives (be specific: "We use Supabase instead of Firebase because...")
- Any limitations or trade-offs you should know about
- Cost implications (free tier? paid? usage-based?)

Format as a table:
| Technology | What It Does Here | Why This One | Watch Out For |
|-----------|------------------|-------------|---------------|

### 6. Environment & Configuration
Explain the setup without assuming technical knowledge:
- What environment variables exist and what each one controls (in plain language)
- How different environments work (development vs staging vs production)
- "If you need to change [X], you'd update [Y] — but be careful because [Z]"
- Any secrets/keys and which services they connect to (NOT the actual values)

### 7. Lessons Learned — The War Stories
This is the most valuable section. Document:

**Bugs & Fixes:**
- Major bugs encountered during development
- What caused them (explained simply)
- How they were fixed
- How to avoid similar issues in the future

**Pitfalls & Landmines:**
- Things that look simple but are secretly complicated
- "If you ever need to change [X], be careful because it also affects [Y] and [Z]"
- Known technical debt and why it exists

**Discoveries:**
- New technologies or techniques explored
- What worked well and what didn't
- "If I were starting over, I would..."

**Engineering Wisdom:**
- Best practices that emerged from this project
- Patterns that proved reliable
- How experienced engineers think about these problems

### 8. Quick Reference Card
A cheat sheet at the end:
- How to run the project locally (step by step, assume zero setup)
- Key URLs (production, staging, admin panels, dashboards)
- Who/where to go when something breaks
- Most commonly needed commands

## Writing Rules — NON-NEGOTIABLE

1. **No unexplained jargon.** Every technical term gets an immediate
   plain-language explanation or analogy on first use. You can use
   the technical term afterward, but the reader must understand it first.

2. **Use analogies aggressively.** Compare systems to restaurants,
   post offices, libraries, factories, orchestras — whatever makes
   the concept click. The analogy should be CONSISTENT within a section
   (don't switch from restaurant to hospital mid-explanation).

3. **Tell the story of WHY.** Don't just document what exists.
   Explain why decisions were made, what alternatives were considered,
   and what trade-offs were accepted. "We went with X because Y,
   even though it means we can't easily do Z later."

4. **Be engaging.** Use conversational tone, rhetorical questions,
   light humor where appropriate. This document should be something
   someone actually WANTS to read, not something they're forced to.
   If a section is boring, rewrite it until it isn't.

5. **Be honest about problems.** Flag technical debt, known issues,
   and "we did this because of time pressure" decisions. This document
   is more useful when it's truthful than when it's polished.

6. **Include "what could go wrong" for every major system.**
   Not to scare, but to prepare. "If the payment service goes down,
   here's what happens and here's what to do."

7. **Use progressive disclosure.** Start each section with the
   simple version, then go deeper. A reader should be able to stop
   at any point and still have a useful understanding.

8. **Format for scannability.** Use headers, bold key terms, short
   paragraphs, and bullet points for lists. But use prose (not bullets)
   for explanations and narratives.

## Example Tone

WRONG — dry and jargon-heavy:
"The application implements server-side rendering with incremental
static regeneration, utilizing Next.js App Router with React Server
Components for optimal TTFB."

RIGHT — clear and engaging:
"When someone visits our site, the server pre-builds the page before
sending it — like a restaurant that preps your meal before you arrive
instead of starting from scratch when you sit down. This is called
'server-side rendering' and it's why pages load fast. We use Next.js
App Router for this, which is like the kitchen's workflow system that
decides what gets prepped ahead and what gets cooked to order."

WRONG — listing without context:
"Dependencies: React 18, Next.js 14, Tailwind CSS, Supabase, Stripe"

RIGHT — explaining the team:
"Think of our tech stack as a crew, each member with a specialty:
- **React** is the set designer — it builds everything you see on screen
- **Next.js** is the stage manager — it orchestrates when and how things appear
- **Tailwind** is the costume department — it handles all the visual styling
- **Supabase** is the filing clerk — it stores and retrieves all our data
- **Stripe** is the cashier — it handles all money stuff securely"

You are updating an existing FORME.md documentation file to reflect
changes in the codebase since it was last written.

## Inputs
- **Current FORGME.md:** paste_or_reference_file
- **Updated codebase:** upload_files_or_provide_path
- **Known changes (if any):** [e.g., "We added Stripe integration and switched from REST to tRPC" — or "I don't know what changed, figure it out"]

## Your Tasks

1. **Diff Analysis:** Compare the documentation against the current code.
   Identify what's new, what changed, and what's been removed.

2. **Impact Assessment:** For each change, determine:
   - Which FORME.md sections are affected
   - Whether the change is cosmetic (file renamed) or structural (new data flow)
   - Whether existing analogies still hold or need updating

3. **Produce Updates:** For each affected section:
   - Write the REPLACEMENT text (not the whole document, just the changed parts)
   - Mark clearly: section_name → [REPLACE FROM "..." TO "..."]
   - Maintain the same tone, analogy system, and style as the original

4. **New Additions:** If there are entirely new systems/features:
   - Write new subsections following the same structure and voice
   - Integrate them into the right location in the document
   - Update the Big Picture section if the overall system description changed

5. **Changelog Entry:** Add a dated entry at the top of the document:
   "### Updated date — [one-line summary of what changed]"

## Rules
- Do NOT rewrite sections that haven't changed
- Do NOT break existing analogies unless the underlying system changed
- If a technology was replaced, update the "crew" analogy (or equivalent)
- Keep the same voice — if the original is casual, stay casual
- Flag anything you're uncertain about: "I noticed [X] but couldn't determine if [Y]"