From e3967d6fe399d48e9eb24b33836b0bd211044181 Mon Sep 17 00:00:00 2001 From: macedo Date: Wed, 21 Jan 2026 15:33:27 +0700 Subject: [PATCH 1/3] docs: restructure commands and add coding guidelines - Replace prompts folder with standardized cursor commands - Add coding-guidelines.md with architecture and style rules - Add new commands: prototype-ui, ship-feature - Update new-feature with clarifying questions step - Update review-pr with architecture compliance checks - Remove old planning docs (consolidated into guidelines) --- docs/commands/README.md | 53 +++ docs/commands/cleanup-ai-slop.md | 12 + docs/commands/commit.md | 43 +++ docs/commands/create-pr.md | 33 ++ docs/commands/new-feature.md | 27 ++ docs/commands/prototype-ui.md | 37 ++ docs/commands/review-pr.md | 58 +++ docs/commands/ship-feature.md | 41 ++ docs/commands/test.md | 19 + docs/features/.gitkeep | 0 docs/guidelines/coding-guidelines.md | 162 ++++++++ docs/planning/coding-principles.md | 113 ------ docs/planning/design-system.md | 352 ------------------ docs/planning/file-structure.md | 70 ---- docs/prompts/1-product-brief.md | 17 - docs/prompts/2-plan-feature.md | 24 -- docs/prompts/3-design-ui.md | 16 - docs/prompts/4-review-code.md | 13 - docs/prompts/5-merge-feature.md | 13 - docs/prompts/6-write-docs.md | 23 -- docs/prompts/README.md | 51 --- docs/prompts/learn to code/LearnToCode.md | 207 ---------- .../ultimate-coding-prompt-guide.md | 349 ----------------- docs/temp/.gitkeep | 0 24 files changed, 485 insertions(+), 1248 deletions(-) create mode 100644 docs/commands/README.md create mode 100644 docs/commands/cleanup-ai-slop.md create mode 100644 docs/commands/commit.md create mode 100644 docs/commands/create-pr.md create mode 100644 docs/commands/new-feature.md create mode 100644 docs/commands/prototype-ui.md create mode 100644 docs/commands/review-pr.md create mode 100644 docs/commands/ship-feature.md create mode 100644 docs/commands/test.md delete mode 100644 docs/features/.gitkeep create mode 100644 docs/guidelines/coding-guidelines.md delete mode 100644 docs/planning/coding-principles.md delete mode 100644 docs/planning/design-system.md delete mode 100644 docs/planning/file-structure.md delete mode 100644 docs/prompts/1-product-brief.md delete mode 100644 docs/prompts/2-plan-feature.md delete mode 100644 docs/prompts/3-design-ui.md delete mode 100644 docs/prompts/4-review-code.md delete mode 100644 docs/prompts/5-merge-feature.md delete mode 100644 docs/prompts/6-write-docs.md delete mode 100644 docs/prompts/README.md delete mode 100644 docs/prompts/learn to code/LearnToCode.md delete mode 100644 docs/prompts/learn to code/ultimate-coding-prompt-guide.md delete mode 100644 docs/temp/.gitkeep diff --git a/docs/commands/README.md b/docs/commands/README.md new file mode 100644 index 0000000..87e395e --- /dev/null +++ b/docs/commands/README.md @@ -0,0 +1,53 @@ +# Cursor User Commands + +This folder contains shared Cursor IDE user commands for the team. These commands help standardize our AI-assisted development workflow. + +## Setup + +To use these commands, copy them to your local Cursor commands folder: + +```bash +# macOS/Linux +cp docs/commands/*.md ~/.cursor/commands/ + +# Or create symlinks to stay in sync +ln -sf "$(pwd)/docs/commands/"*.md ~/.cursor/commands/ +``` + +## Available Commands + +| Command | Description | +|---------|-------------| +| `/new-feature` | Start a new feature or bug fix connected to a GitHub issue | +| `/prototype-ui` | Explore UI/UX approaches before committing to implementation | +| `/cleanup-ai-slop` | Review and remove AI-generated code patterns that don't match our codebase style | +| `/commit` | Create well-structured git commits with conventional commit format | +| `/test` | Run all checks (lint, types, tests) and fix failures iteratively | +| `/review-pr` | Run automated checks and code review before asking for human review | +| `/create-pr` | Create a pull request with proper description, labels, and reviewers | +| `/ship-feature` | Post-merge cleanup: close issues, changelog, docs ⚠️ *WIP* | + +## Workflow + +**Starting a feature:** +1. `/new-feature` - Create branch from GitHub issue, clarify requirements, validate understanding +2. `/prototype-ui` - *(optional)* Explore UI approaches before building + +**During development:** +- `/test` - Run tests after making changes, fix failures iteratively + +**When finishing a feature:** +1. `/cleanup-ai-slop` - Clean up any AI artifacts +2. `/commit` - Create atomic, well-described commits +3. `/review-pr` - Run in a **new chat session** to validate before human review +4. `/create-pr` - Open a PR with proper metadata + +**After merge:** +- `/ship-feature` - Close issues, update changelog, trigger docs ⚠️ *WIP* + +## Contributing + +When updating these commands: +1. Edit the files in this folder +2. Test the changes locally +3. Commit with `docs(commands): ` diff --git a/docs/commands/cleanup-ai-slop.md b/docs/commands/cleanup-ai-slop.md new file mode 100644 index 0000000..11fbac0 --- /dev/null +++ b/docs/commands/cleanup-ai-slop.md @@ -0,0 +1,12 @@ +# cleanup-ai-slop + +Check the diff against main, and remove all AI generated slop introduced in this branch. + +This includes: + +- Extra comments that a human wouldn't add or is inconsistent with the rest of the file +- Extra defensive checks or try/catch blocks that are abnormal for that area of the codebase (especially if called by trusted / validated codepaths) +- Casts to any to get around type issues +- Any other style that is inconsistent with the file + +Report at the end with only a 1-3 sentence summary of what you changed diff --git a/docs/commands/commit.md b/docs/commands/commit.md new file mode 100644 index 0000000..e2cb984 --- /dev/null +++ b/docs/commands/commit.md @@ -0,0 +1,43 @@ +# commit + +You are tasked with creating git commits for the changes made during this session. + +## Process: + +1. **Think about what changed:** + - Review the conversation history and understand what was accomplished + - Run `git status` to see current changes + - Run `git diff` to understand the modifications + - Consider whether changes should be one commit or multiple logical commits + - Check if the user ran the following cursor command: /cleanup-ai-slop, and if not prompt him to do it first + +2. **Plan your commit(s):** + - Identify which files belong together + - Draft clear, descriptive commit messages + - Use imperative mood in commit messages + - Focus on why the changes were made, not just what + +3. **Present your plan to the user:** + - List the files you plan to add for each commit + - Show the commit message(s) you'll use + - Ask: "I plan to create [N] commit(s) with these changes. Shall I proceed?" + +4. **Execute upon confirmation:** + - Use `git add` with specific files (never use `-A` or `.`) + - Create commits with your planned messages + - Show the result with `git log --oneline -n [number]` + +## Important: +- **NEVER add co-author information or Claude attribution** +- Commits should be authored solely by the user +- Do not include any "Generated with Claude" messages +- Do not add "Co-Authored-By" lines +- Write commit messages as if the user wrote them +- Keep descriptions concise, lowercase, and in present tense without periods. +- Use Conventional Commits format: `(scope): `. Scope is optional. Use types like feat:, fix:, chore:, docs:, refactor:, perf:, test:. Add ! for breaking changes (e.g., feat!: or feat(api)!:). + +## Remember: +- You have the full context of what was done in this session +- Group related changes together +- Keep commits focused and atomic when possible +- The user trusts your judgment - they asked you to commit diff --git a/docs/commands/create-pr.md b/docs/commands/create-pr.md new file mode 100644 index 0000000..9241326 --- /dev/null +++ b/docs/commands/create-pr.md @@ -0,0 +1,33 @@ +# create-pr + +## Overview +Create a well-structured pull request with proper description, labels, and reviewers. + +## Steps +1. **Pre-flight check** + - Ask the user: "Have you run `/review-pr` in a fresh session? (yes/no)" + - If no, prompt them to run it first before creating the PR + +2. **Prepare branch** + - Ensure all changes are committed + - Push branch to remote + - Verify branch is up to date with main + +3. **Write PR description** + - Summarize changes clearly + - Include context and motivation + - List any breaking changes + - Add screenshots if UI changes + +4. **Set up PR** + - Create PR with descriptive title + - Add appropriate labels (by default should be "talent-app", but ask user to confirm) + - Assign reviewers (by default assign to @simaonogueira101, but ask user to confirm) + - Make me (@filmacedo) the Assignee + - Link related issues + +## PR Template +- [ ] Feature A +- [ ] Bug fix B +- [ ] Unit tests pass +- [ ] Manual testing completed diff --git a/docs/commands/new-feature.md b/docs/commands/new-feature.md new file mode 100644 index 0000000..36999da --- /dev/null +++ b/docs/commands/new-feature.md @@ -0,0 +1,27 @@ +# new-feature + +Start working on a new feature or bug fix connected to a GitHub issue. + +## Process + +1. **Get context:** + - Ask: "What's the GitHub issue number or URL?" + - Fetch the issue details with `gh issue view ` + - Read and understand the requirements + - Review @coding-guidelines.md to understand architecture patterns + +2. **Clarify before building:** + - If requirements are unclear, ask up to 5 clarifying questions + - Ensure there's no ambiguity before starting implementation + - Don't assume — if something could be interpreted multiple ways, ask + +3. **Create branch:** + - Branch from main: `git checkout main && git pull && git checkout -b /-` + - Use `feat/` for features, `fix/` for bugs (e.g., `feat/123-add-dark-mode`) + +4. **Quick validation:** + - Summarize what needs to be done in 2-3 sentences + - Ask: "Does this match your understanding? Anything to add or clarify?" + +5. **Start working:** + - Once confirmed, begin implementation diff --git a/docs/commands/prototype-ui.md b/docs/commands/prototype-ui.md new file mode 100644 index 0000000..39dd8d7 --- /dev/null +++ b/docs/commands/prototype-ui.md @@ -0,0 +1,37 @@ +# prototype-ui + +Explore UI/UX approaches before committing to implementation. + +## When to Use + +- New pages or major UI features +- When the design isn't obvious from the requirements +- When you want to see options before building + +## Process + +1. **Get context:** + - Ask for the feature description or GitHub issue + - Understand the user flow and data requirements + - Review existing similar components in the codebase + +2. **Generate 3 approaches:** + - Describe each approach in natural language (no code yet) + - Focus on layout, interaction patterns, and user flow + - Highlight trade-offs between approaches + - Use simple diagrams or ASCII sketches if helpful + +3. **Get feedback:** + - Ask: "Which approach do you prefer, or what would you combine?" + - Incorporate feedback into a final direction + +4. **Build the prototype:** + - Create a functional prototype with real or mock data + - Focus on the UI structure and interactions + - Don't worry about edge cases or error handling yet + - Follow @coding-guidelines.md for component patterns + +5. **Iterate:** + - Show the prototype and ask for feedback + - Refine until the direction is confirmed + - Then proceed to full implementation diff --git a/docs/commands/review-pr.md b/docs/commands/review-pr.md new file mode 100644 index 0000000..566cd93 --- /dev/null +++ b/docs/commands/review-pr.md @@ -0,0 +1,58 @@ +# review-pr + +Pre-review checklist to run before asking a human to review your PR. + +## Pre-flight Check + +**Start fresh:** If you've been working in this session, the context may be polluted. + +Ask the user: "Is this a fresh chat session? (yes/no)" +- If no: "Please start a new chat and run /review-pr again." +- If yes: Proceed with the review. + +## Process + +1. **Run automated checks:** + ```bash + npx turbo run lint check-types && npm test + ``` + - Fix all errors and warnings before proceeding + - If tests fail, investigate and fix the root cause + +2. **Review the diff:** + - Run `git diff main` to see all changes + - Check for component reuse - are we duplicating existing components? + - Verify styles match the rest of the app + - Look for hardcoded values that should be constants or configs + - Ensure no console.logs or debugging code left behind + +3. **Code quality check:** + - Proper error handling where needed + - No unused imports or variables + - Consistent naming conventions + - Types are specific (avoid `any`) + +4. **Architecture compliance:** + - Review @coding-guidelines.md + - Verify hooks use `isServer` pattern + - Verify services use `unstable_cache` + - Check semantic colors only (no `bg-gray-*`, use `bg-muted` etc.) + - Ensure components use hooks, not direct API calls + +5. **Security check:** + - No hardcoded secrets, API keys, or credentials + - Input validation on user-facing endpoints + - Sensitive data not logged or exposed in errors + - No dangerous patterns (eval, dangerouslySetInnerHTML without sanitization) + +6. **Report findings:** + - List any issues found with file locations + - Suggest fixes or improvements + - Confirm when all checks pass + +## Output + +End with a summary: +- ✅ Checks passed / ❌ Issues found +- List of changes made (if any) +- "Ready for human review" or "Fix these issues first" diff --git a/docs/commands/ship-feature.md b/docs/commands/ship-feature.md new file mode 100644 index 0000000..281e9bd --- /dev/null +++ b/docs/commands/ship-feature.md @@ -0,0 +1,41 @@ +# ship-feature + +> ⚠️ **WIP**: This command is a work in progress. Versioning and changelog workflows are not yet established. + +Post-merge cleanup after a PR has been merged. + +## When to Use + +Run this after your PR has been merged to main. + +## Process + +1. **Confirm merge:** + - Ask: "Has the PR been merged? What was the PR number?" + - Verify the PR is closed/merged on GitHub + +2. **Update GitHub issue:** + - Close the linked issue if not auto-closed + - Add a comment summarizing what was implemented + - Link to the merged PR + +3. **Changelog entry:** *(future)* + - Create `docs/changelog/YYYY-MM-DD-.md` + - Include: what changed, why, any breaking changes + - Keep it user-facing (not implementation details) + +4. **Version bump:** *(future)* + - Determine bump type: patch (fixes), minor (features), major (breaking) + - Ask user to confirm before bumping + +5. **Documentation:** + - Ask: "Does this feature need documentation updates?" + - If yes, identify what docs need updating + - Update inline code comments if helpful for future maintainers + +## Output + +Summary of post-merge tasks completed: +- ✅ Issue closed +- ✅ Changelog entry created +- ✅ Docs updated (if needed) diff --git a/docs/commands/test.md b/docs/commands/test.md new file mode 100644 index 0000000..bcdd97e --- /dev/null +++ b/docs/commands/test.md @@ -0,0 +1,19 @@ +# test + +Run the full test suite and systematically fix any failures. + +## Process + +1. **Run all checks:** + ```bash + npx turbo run lint check-types && npm test + ``` + +2. **On failure:** + - Fix one issue at a time + - Re-run after each fix + - Never skip or disable tests without explicit user approval + +3. **Report:** + - ✅ All checks pass / ❌ N issues found + - Brief summary of fixes made diff --git a/docs/features/.gitkeep b/docs/features/.gitkeep deleted file mode 100644 index e69de29..0000000 diff --git a/docs/guidelines/coding-guidelines.md b/docs/guidelines/coding-guidelines.md new file mode 100644 index 0000000..ae7b120 --- /dev/null +++ b/docs/guidelines/coding-guidelines.md @@ -0,0 +1,162 @@ +# Talent Coding Guidelines + +## Architecture Rules (Enforced) + +### Use axios, not fetch + +```typescript +// ❌ Linter error +const res = await fetch('/api/profile'); + +// ✅ Required +const res = await axios.get('/api/profile'); +``` + +### Components use hooks, not API routes + +```typescript +// ❌ Linter error - direct API call in component +const data = await axios.get('/api/profile'); + +// ✅ Required - use hooks +const { data } = useProfile({ profileId }); +``` + +### Hooks must use isServer pattern + +```typescript +// ✅ Required pattern in hooks +queryFn: async () => { + if (isServer) { + return fetchProfile({ talentId }); // Direct service call + } + return axios.get('/api/profile').then(r => r.data); // API route +} +``` + +### Services must use unstable_cache + +```typescript +// ✅ Required for services (except mutations) +export const fetchProfile = unstable_cache( + async (options) => { + return axios.get(`${API_URL}/profile`); + }, + ["profile"], + { revalidate: 300 } +); +``` + +Exceptions: internal helpers (`_prefixed`), mutations (POST/PUT/PATCH/DELETE). + +--- + +## Tailwind Rules (Enforced) + +### Semantic colors only + +```typescript +// ❌ Linter error +className="bg-gray-100 text-blue-500 border-red-300" + +// ✅ Required - semantic tokens +className="bg-muted text-foreground border-border" +``` + +Allowed: `background`, `foreground`, `card`, `muted`, `accent`, `primary`, `secondary`, `destructive`, `warning`, `success`, `border`, `input`, `ring`, plus `-foreground` variants. + +### Design system values only + +```typescript +// ⚠️ Warning - arbitrary values +className="p-[13px] text-[17px] rounded-[7px]" + +// ✅ Use scale values +className="p-4 text-base rounded-lg" +``` + +--- + +## TypeScript Rules (Enforced) + +### Strict mode enabled + +- `noUncheckedIndexedAccess` — array/object access may be `undefined` +- `isolatedModules` — each file compiled independently + +### Underscore prefix for intentional unused + +```typescript +// ❌ Linter error +const unused = getValue(); + +// ✅ Allowed - underscore prefix +const _intentionallyUnused = getValue(); +``` + +--- + +## Conventions (Not Enforced) + +These aren't linted but are team standards. + +### CACHE_TAGS for query keys + +Use constants from `@talent/data/constants` instead of string literals. This ensures cache invalidation works consistently across the app and prevents typos. + +```typescript +// ❌ Avoid +queryKey: ["profile", profileId] + +// ✅ Preferred +queryKey: [CACHE_TAGS.TALENT_PROFILE_QUERY, profileId] +``` + +### useSuspenseQuery + Skeletons + +Prefer `useSuspenseQuery` over `useQuery` for data that's always needed. Wrap with Suspense boundaries and skeleton fallbacks that match the final layout. + +```tsx +}> + + +``` + +Skeletons live in `@talent/ui/components/common/skeletons/`. + +### Named imports, no barrel files + +Always use named imports and import directly from the file, not from `index.ts` barrels. This speeds up builds and makes dependencies explicit. + +```typescript +// ❌ Avoid +import Button from "@talent/ui"; +import { Button } from "@talent/ui"; + +// ✅ Preferred +import { Button } from "@talent/ui/components/ui/button"; +``` + +### Shared packages first + +Default to shared packages before creating app-specific code. This reduces duplication and keeps the codebase consistent. + +| Package | Purpose | +|---------|---------| +| `@talent/data` | Services, hooks, types, constants | +| `@talent/ui` | Shared UI components (shadcn/ui base) | +| `@talent/query` | TanStack Query configuration | + +Only create app-specific code when the functionality is truly unique to one app. + +--- + +## Quick Reference + +``` +❌ fetch() → ✅ axios +❌ API call in component → ✅ use hook +❌ bg-gray-100 → ✅ bg-muted +❌ text-[17px] → ✅ text-base +❌ const unused → ✅ const _unused +``` diff --git a/docs/planning/coding-principles.md b/docs/planning/coding-principles.md deleted file mode 100644 index 8cd957b..0000000 --- a/docs/planning/coding-principles.md +++ /dev/null @@ -1,113 +0,0 @@ -# Creator Score App – Architecture & Core Principles - -## CORE PRINCIPLES -- Modular data flow: External APIs → Services → API Routes → Hooks → UI Components -- Client-server separation: No direct service imports in client code -- Pure UI components: Data via props only, no API calls - -## TECHNICAL ARCHITECTURE - -### Core Architecture Pattern: Modular Data Flow - -**CRITICAL**: This app follows a **strict modular architecture** where: - -``` -External APIs → API Clients → Services → Route Handlers → Hooks → Pure UI Components -``` - -#### Layer Responsibilities: - -1. **API Clients Layer** (lib/): Abstracted external API interactions with shared utilities -2. **Services Layer**: Domain-specific business logic and data transformations (consumed by Server Components and Route Handlers) -3. **Route Handlers Layer**: Server-side HTTP endpoints in `app/api/*` that call services; consumed by browsers/clients, webhooks, and external integrations -4. **Hooks Layer**: Client-side data fetching and state management via Route Handlers (no direct service imports) -5. **Components Layer**: Pure UI components that receive data via props only; Server Components prefer calling services directly - -#### Client-Server Separation Rules - -**FUNDAMENTAL PRINCIPLE**: Strict separation between client-side and server-side code is mandatory. - -**REQUIRED PATTERN**: - -``` -❌ PROHIBITED: Client Hook → Direct Service Import → External API -✅ SERVER: Route Handler → Service → External API -✅ CLIENT: Client Hook → Fetch → Route Handler → Service → External API -``` - -**Architecture Rules**: - -- Client-side code (hooks, components) NEVER directly imports server-side services -- Client-side data fetching flows through Route Handlers (`app/api/*`) or Server Actions; Server Components call services directly -- Server-only packages (Node.js SDKs, secrets) exist only in server code (services and Route Handlers) -- Use `server-only` to guard server modules and avoid accidental client bundling -- This ensures clean separation, smaller client bundles, and prevents runtime errors - -### Next.js App Router Best Practices - -- Default to Server Components; mark Client Components explicitly with `use client` -- Keep server-only code out of client bundles using `server-only` and by isolating services under `lib/`/`app/api/` -- use Route Handlers for browser-accessible reads, mutations, and webhooks -- Use `error.tsx` and `loading.tsx` per route segment; leverage Suspense for progressive rendering -- Define page metadata via `generateMetadata`; avoid client-only SEO hacks - -### Product Analytics - -Use posthog to keep track of new features usage. Include event tracking on the action to track to ensure consistent implementation and easyness to remove. - -### Data Fetching Principles - -- **Hook Interface Standard**: All client hooks return `{data, loading, error}` consistently -- **Hook Naming**: `useProfile*` for profile data, `useLeaderboard*` for leaderboard, `useUser*` for current user (etc..) -- **Server-Side URL Resolution**: Always use absolute URLs in server contexts; relative URLs fail in SSR/API routes/build-time -- **Caching Location**: - - Server Components: prefer `fetch` with `next: { revalidate, tags }` - - Services: use `unstable_cache` for heavy/shared computations - - Route Handlers: set `export const revalidate` or response headers and use `revalidateTag` after mutations/data changes -- **Cache Tags & TTLs**: Use tags like `profile:${uuid}`, `leaderboard:global`. Define TTLs in code near services (constants) and prefer tag-based invalidation over long TTLs -- **Error Handling**: Graceful fallbacks with skeleton loaders; segment-level `error.tsx` for recoverability - -### Component Interface Standards - -- **Page Components**: Accept only routing/identifier props, use hooks for data -- **UI Components**: Pure functions receiving all data via props, no API calls -- **Reusability**: Default to shadcn/ui, create custom components only for unique UX needs - - -### User Resolution System - -- Use `Talent UUID` as the canonical user ID and resolve identifiers (Farcaster, wallet, GitHub, ...) via `lib/user-resolver.ts`. -- Mini apps detect user context via Farcaster SDK and convert FID to Talent UUID, while browsers use wallet authentication to convert address into Talent UUID. - - -### Type Organization - -- **Types**: All TypeScript types organized in `lib/types/` by domain. - -### Tech Stack & Performance - -- **Framework**: Next.js 15 (App Router), React 18+, shadcn/ui, Tailwind CSS -- **Authentication**: Farcaster SDK + Privy SDK (wallet-only authentication) with development mode bypass -- **State Management**: React hooks + context (no external state library) -- **Caching**: Next.js caching via `fetch` revalidation/tags and `unstable_cache`; avoid client-side caches unless necessary -- **TypeScript**: Strict mode with comprehensive typing throughout - -### External API Standards - -- **Security**: Never expose secrets to the client; mask sensitive data in logs; verify webhook signatures -- **Observability**: Structured logs with `{ provider, operation, requestId, status, durationMs }`; emit basic latency/error metrics -- **Talent API Data Usage:** Always ignore `points_calculation_logic` in Talent API responses and use only top-level credential fields (slug, points, readable_value, uom, max_score, etc.) for all logic and display. - -### Caching & Revalidation Model - -- Prefer `fetch` with `next: { revalidate, tags }` in Server Components; use tag-based invalidation after writes -- Wrap heavy services with `unstable_cache` to share results across routes/renderings -- Use `revalidateTag` in mutation Route Handlers to invalidate related reads - -### Design Principles - -- Mobile-first and responsive. See `docs/planning/design-system.md` for typography, color, layout, and component patterns. - -### Content Management Principles - -- **Content-Logic Separation**: Always separate content (copy, labels, descriptions) from business logic (computation, validation, data processing). diff --git a/docs/planning/design-system.md b/docs/planning/design-system.md deleted file mode 100644 index a7e6926..0000000 --- a/docs/planning/design-system.md +++ /dev/null @@ -1,352 +0,0 @@ -# Creator Score App - Design System - -## Core Principles - -### 1. Semantic-First Approach - -- **Default to semantic classes** (`text-foreground`, `bg-muted`, `border-border`) for theme consistency -- **Avoid hardcoded colors** unless for specific brand moments - -### 2. Mobile-First Design - -- **Touch interactions only** - no hover states on mobile -- **Bottom sheets** for modals on mobile, centered dialogs on desktop -- **Responsive breakpoint**: `640px` (sm+) - -### 3. Minimal & Elegant - -- **Smaller, thinner fonts** with more white space -- **Consistent spacing** using established patterns -- **Clean, uncluttered interfaces** - -## Color System - -### Semantic Colors (Default) - -- **Background**: `bg-background` / `bg-muted` -- **Text**: `text-foreground` / `text-muted-foreground` -- **Borders**: `border-border` - -### Brand Colors - -- **Primary**: Tailwind purple-700 #7e22ce -- **Secondary**: - - Tailwind lime-600 #84cc16 - - Tailwind cyan-600 #0e7490 - - Tailwind pink-600 #be185d - -### Usage Rules - -1. **Start with semantic classes** for all standard UI -2. **Use brand colors only** for: - - Rewards and earnings - - Primary CTAs - - Data visualization (SegmentedBar, PostsChart) - - Brand identity moments - -### Example Usage - -```tsx -// ✅ GOOD: Use semantic classes for theme consistency -
-

Main content

- Secondary text -
- -// ✅ GOOD: Use specific colors for intentional brand elements -
Brand moments (rewards, CTAs)
-
Brand callouts
- -// ❌ BAD: Hardcoded colors instead of semantic classes -
-``` - -### Brand Accent System (core) - -- **Token**: Tailwind `brand-purple` color maps to `hsl(var(--creator-purple))`. -- **Defaults**: Brand colors are now explicit variants: `brand-purple`, `brand-green`, `brand-blue`, `brand-pink`. -- **Override**: Use explicit variant props instead of dynamic accent system. -- **Utilities**: Use `text-brand`, `bg-brand/10`, `bg-brand/20`, `hover:bg-brand/30` for washes and states. -- **Components**: Brand variants accept `color?: 'purple'|'green'|'blue'|'pink'` to set the accent per instance. - -## Component Patterns - -### Cards - -**Base Pattern**: All cards use the foundational `Card` component with semantic styling. - -**Variants**: - -- **Content Cards**: Standard `bg-card` with border and shadow -- **Muted Cards**: `bg-muted` with `border-0 shadow-none` for subtle sections -- **Interactive Cards**: Add hover states and click handlers - -**Common Patterns**: - -- **Stat Cards**: Title/value pairs with optional click handlers -- **List Cards**: Avatar lists with rankings or data -- **Progress Cards**: Score displays with progress visualization -- **Accordion Cards**: Expandable content sections - -### Buttons - -**Base Button**: Standard semantic variants with consistent sizing -**ButtonFullWidth**: Section-level actions with required icons and left alignment - -### Callouts & Carousel - -- **Callout variants**: `brand` and `muted`. Brand reads `text-brand`/`bg-brand/20`. -- **Accent control**: Set per-instance via explicit variant props (`brand-purple|brand-green|brand-blue|brand-pink`). -- **Typography**: Title = `size="base"` + `weight="medium"` (brand color for `brand`, default otherwise). Description = `size="sm"`, `color="muted"`. Left-aligned. -- **Icons**: Left icon uses brand accent for `brand`, `text-foreground` for `muted`. Right arrow/close `X` are `text-muted-foreground`. -- **Interactivity**: Entire callout clickable when `href` is set. If `onClose` is present, close takes priority but the rest remains clickable. -- **Dismissal**: Season-aware persistence in `localStorage` using a round-specific key. -- **CalloutCarousel**: Mobile-first horizontal snap (`snap-x snap-mandatory`), one slide per viewport, hides scrollbar, aligns with page padding (no negative margins), disables overflow when single item. - -### Interactive States - -- **Hover**: `hover:bg-muted/50` for non-card elements -- **Active**: Semantic color variants -- **Disabled**: `opacity-50 cursor-not-allowed` -- **Loading**: Consistent skeleton patterns - -## Layout Standards - -### Page Structure - -**All pages use `PageContainer` + `Section` components for consistent layout and spacing.** - -**Single Pattern (All Pages):** - -```tsx - -
Title & context
-
Tabs/dividers (edge-to-edge)
-
Main content
- -``` - -**Section variants handle all padding:** - -- **`header`**: `px-4 pt-6 pb-3` - Page titles and context -- **`content`**: `px-4 py-4` - Main content with padding -- **`full-width`**: `w-full` - Edge-to-edge elements (tabs, dividers) - -**PageContainer provides:** - -- **Layout structure**: `min-h-screen` + `overflow-y-auto` + `relative` -- **Max-width constraint**: `max-w-xl` (576px) for consistent mobile design -- **Responsive bottom spacing**: `pb-24` (mobile) + `md:pb-4` (desktop) -- **No horizontal padding**: Section variants handle all content spacing - -### Spacing Scale - -- **Large**: `mb-6 sm:mb-8` -- **Default**: `mb-4 sm:mb-6` -- **Compact**: `mb-3 sm:mb-4` -- **Internal**: `p-4 sm:p-6` (regular), `p-3 sm:p-4` (compact) - -### Z-Index Hierarchy - -- **Content**: 0-10 -- **Header**: 30 -- **Navigation**: 40 -- **Modals**: 50 - -## Typography - -### Typography Component - -The `Typography` component provides consistent text styling across the app using semantic classes and the established design system. - -**Usage:** - -```tsx -import { Typography } from "@/components/ui/typography"; - -// Basic usage -Default body text - -// With variants - - Small, medium weight, muted text - - -// As different elements - - Page heading - -``` - -**Available Variants:** - -- **Size**: `xs`, `sm`, `base`, `lg`, `xl`, `2xl` -- **Weight**: `light`, `normal`, `medium`, `bold` -- **Color**: `default`, `muted`, `brand` -- **Element**: `p`, `span`, `div`, `h1`-`h6` - -> **Note**: The Typography component (`components/ui/typography.tsx`) is the single source of truth for all typography values. Refer to the component implementation for the complete list of available options. - -### Guidance - -- Always use `components/ui/typography.tsx` to set typography variants (size, weight, color) in components and pages. Avoid ad‑hoc Tailwind text classes for text styling to maintain semantic, theme-safe consistency. - -### Typography Principles - -- **Semantic Colors**: Use `default`, `muted`, or `brand` colors for consistent theming -- **Responsive Sizes**: Most sizes include responsive variants (e.g., `text-sm sm:text-[15px]`) -- **Element Semantics**: Use appropriate HTML elements (`h1`-`h6` for headings, `p` for paragraphs) -- **Consistent Spacing**: Typography components work with the established spacing scale - -### Component Integration - -**Callout Component**: Updated to use children composition instead of `textSize` prop: - -```tsx -// ✅ GOOD: Use Typography component for text styling - - Connect accounts to increase your Creator Score - - -// ✅ GOOD: Direct children for simple text - - Simple text without special styling - -``` - -### Migration Guide - -**From `textSize` prop to `Typography` component:** - -```tsx -// ❌ OLD: Using textSize prop - - Connect accounts to increase your Creator Score - - -// ✅ NEW: Using Typography component - - - Connect accounts to increase your Creator Score - - -``` - -**Benefits of the new approach:** - -- **Flexibility**: Easy to add bold, different colors, or other typography variations -- **Composability**: Combine any typography variant with any callout variant -- **Reusability**: Typography component can be used anywhere, not just in callouts -- **Maintainability**: Changes to typography don't require changes to layout components -- **Separation of concerns**: Callout handles layout/styling, Typography handles text styling - -## Data Visualization - -### SegmentedBar - -- **Colors**: Brand colors only (`purple`, `green`, `blue`, `pink`) -- **Usage**: `green` for earnings, `pink` for followers, `blue` for posts, `purple` for score - -### PostsChart - -- **Colors**: Brand colors cycling through years -- **Pattern**: `purple-500` → `green-500` → `blue-500` → `pink-500` - -## Icon System - -### Sizes - -- **Large**: 24px (navigation) -- **Medium**: 18px (engagement) -- **Small**: 14px (indicators) - -### States - -- **Default**: `text-muted-foreground stroke-[1.5]` -- **Active**: `text-foreground stroke-2` -- **Disabled**: `opacity-20` - -### Interactions - -- **Click effect**: Scale + stroke weight change -- **No hover states** (mobile-first) - -## Loading & Error States - -### Loading Patterns - -- **Skeleton loaders** with `animate-pulse` -- **Progress indicators** for complex operations -- **Consistent messaging** across all components - -### Error Handling - -- **Graceful fallbacks** with helpful messaging -- **Retry mechanisms** where appropriate -- **No crashes** - always show something - -## Accessibility - -### Focus Management - -- **Visible focus rings** with `focus-visible:ring-2` -- **Proper tab order** and keyboard navigation -- **Screen reader support** with `aria-*` attributes - -### Color Contrast - -- **WCAG AA compliance** for all text combinations -- **Semantic color usage** ensures proper contrast - -## Animation Guidelines - -### Transitions - -- **Page transitions**: `animate-in fade-in duration-300` -- **Modal animations**: `slide-in-from-bottom` (mobile), `zoom-in` (desktop) -- **Interactive feedback**: `active:scale-95` for buttons - -### Performance - -- **Hardware acceleration** for smooth animations -- **Reduced motion** support for accessibility -- **Consistent timing** across all interactions - -## Modal Backdrop (Blurred Scrim) - -### Shared Pattern - -- **Overlay utility**: `.modal-overlay` -- **Default styles**: `bg-black/70 backdrop-blur-sm` with fade in/out via data state classes. -- **Scope**: Applied to both `Dialog` (desktop) and `Drawer` (mobile) overlays for uniform feel. - -### Usage - -- The utility is defined in `app/theme.css` and used by `components/ui/dialog.tsx` and `components/ui/drawer.tsx`. -- To customize per-use, pass `className` to `DialogOverlay` or `DrawerOverlay` and compose with `modal-overlay`. - -### Guidance - -- **Subtle by default**: stick with `backdrop-blur-sm` and `bg-black/70` for performance and clarity. -- **Performance note**: backdrop blur can impact low-end devices; avoid increasing blur strength globally. -- **No background scaling**: Drawers do not scale the background by default. - -## Component Decision Tree - -### When to Create New Components - -1. **Reused 3+ times** across different contexts -2. **Complex interaction patterns** that need abstraction -3. **Consistent visual patterns** that vary only in data - -### When to Use Existing Components - -1. **Standard patterns** (cards, buttons, lists) -2. **Minor variations** can be handled with props -3. **Consistent behavior** across the app - -### When to Use Semantic Classes - -1. **Simple styling** that doesn't need abstraction -2. **One-off variations** of existing components -3. **Layout and spacing** patterns diff --git a/docs/planning/file-structure.md b/docs/planning/file-structure.md deleted file mode 100644 index ca3b303..0000000 --- a/docs/planning/file-structure.md +++ /dev/null @@ -1,70 +0,0 @@ -# File Structure Framework - -## Turborepo Structure -``` -turborepo/ -├── apps/ -│ └── [app-name]/ # Individual applications -│ ├── app/ # Next.js App Router -│ ├── components/ # App-specific components -│ ├── hooks/ # App-specific hooks -│ └── lib/ # App-specific utilities -├── packages/ -│ ├── ui/ # Shared UI components -│ ├── config/ # Shared configurations -│ ├── types/ # Shared TypeScript types -│ └── utils/ # Shared utilities -``` - -## App-Level Structure -``` -app-name/ -├── app/ # Next.js App Router -│ ├── api/ # API routes -│ ├── [feature]/ # Feature pages -│ ├── services/ # Server-side services -│ └── layout.tsx -├── components/ -│ └── [feature]/ # Feature components -├── hooks/ # Custom React hooks -├── lib/ # Utilities & config -│ ├── types/ # TypeScript type definitions -│ │ ├── index.ts # Re-exports for convenient imports -│ │ ├── profiles.ts # Profile, wallet, settings types -│ └── [other-utils]/ # Other utilities -├── public/ # Static assets -└── docs/ # Documentation -``` - -## Naming Conventions -- **Files**: kebab-case (`user-profile/`, `api-client.ts`) -- **Components**: PascalCase (`UserProfile.tsx`) -- **Functions/Hooks**: camelCase (`useUserProfile`) -- **Services**: `[Domain]Service` (`UserService`) -- **Hooks**: `use[Feature]Data` (`useProfileData`) -- **Type Files**: kebab-case (`social-accounts.ts`, `user-preferences.ts`) -- **Type Interfaces**: PascalCase (`UserProfile`, `SocialAccount`) - -## Architecture Patterns -- **Service Layer**: Business logic in `/app/services/` -- **Hook Pattern**: Data fetching in `/hooks/api/` -- **Component Pattern**: Pure UI in `/components/[feature]/` -- **Type Organization**: Domain-specific types in `/lib/types/[domain].ts` -- **Import Order**: React → Third-party → Internal → Relative - -## Configuration -- Environment: `lib/config/env.ts` -- Features: `lib/config/features.ts` -- Constants: `lib/config/constants.ts` - - -## Key Decisions -- Services: Server-side only (`/app/services/`) -- API Clients: Shared utilities (`/lib/api/clients/`) -- Type Safety: Strict TypeScript, interfaces over types -- Error Handling: `{ data, error }` pattern - -## References -- [Pattern Examples](./patterns/) -- [Component Guidelines](./components/) -- [API Documentation](./api/) \ No newline at end of file diff --git a/docs/prompts/1-product-brief.md b/docs/prompts/1-product-brief.md deleted file mode 100644 index 896d053..0000000 --- a/docs/prompts/1-product-brief.md +++ /dev/null @@ -1,17 +0,0 @@ -# Context -You are an expert product manager your role is to work with me the product owner to generate a Product Brief. This document will be in markdown format and used to help other LLMs understand the Product. - -# Instructions -Please create a product brief based on the description that the user provides. Your goal is to capture the business and functional requirements of the product and to provide solid context for others working on the product. - -Before writing the brief, review the description for potential issues and propose improvements through conversation with the user. If the user's requirements are unclear you may ask up to 5 clarifying questions before writing the plan. If you do so, incorporate the user's answers into the plan. Ensure there's no ambiguity before proceeding. - -# Document -The product brief should include: -1. Project overview / description -2. Target audience (who is this app for) -3. Primary benefits / features (what does it do) -4. High-level tech/architecture used (how it works) - -Keep the brief very concise and to the point just to give enough context to understand the bigger picture. -Write the document into docs/PRODUCT_BRIEF.md (unless a different file name is specified) \ No newline at end of file diff --git a/docs/prompts/2-plan-feature.md b/docs/prompts/2-plan-feature.md deleted file mode 100644 index 83478ba..0000000 --- a/docs/prompts/2-plan-feature.md +++ /dev/null @@ -1,24 +0,0 @@ -The user will provide a feature description. -Your job as a senior engineer is to: - -1. Create a technical plan that concisely describes the feature the user wants to build. -2. Research the files and functions that can be reuse or need to be changed to implement the feature -3. Avoid any product manager style sections (no success criteria, timeline, migration, etc) -4. Avoid writing any actual code in the plan. -5. Include specific and verbatim details from the user's prompt to ensure the plan is accurate. - -This is strictly a technical requirements document that should: -1. **Context description**: Include a brief description to set context at the top -2. **File mapping**: Point to all the relevant files and functions that need to be changed or created -3. **Flowchart diagram**: Create a Mermaid diagram showing the complete user flow and technical architecture (UI → API → Services → External APIs) with data flow, caching, and error handling. -4. **Code explanation**: Explain any algorithms that are used in natural language. -5. **Architecture compliance**: Ensure the plan follows Hook → API Route → Service → External API pattern and maintains client-server separation. Check @docs/planning/coding-principles.md for more coding guidelines. -6. **Design system**: Verify UI components use semantic colors, Typography component, and mobile-first responsive patterns. Check @docs/planning/design-system.md for more design guidelines. -7. **Code reuse**: Prioritize reusing existing components and services over creating new ones, minimize code changes -8. **Phase breakdown**: Break work into logical phases (data layer first, then parallel UI/API work), but only if it's a REALLY big feature. Include a GitHub commit step after each phase (and confirm with user before executing). - -Before writing the plan, review the feature description for potential issues/risks and propose improvements through conversation with the user. If the user's requirements are unclear, especially after researching the relevant files, you may ask up to 5 clarifying questions before writing the plan. If you do so, incorporate the user's answers into the plan. Ensure there's no ambiguity before proceeding. - -Prioritize being concise and precise. Make the plan as tight as possible without losing any of the critical details from the user's requirements. - -Write the plan into an docs/features/_PLAN.md file with the next available feature number (starting with 0001). diff --git a/docs/prompts/3-design-ui.md b/docs/prompts/3-design-ui.md deleted file mode 100644 index dd6b5a3..0000000 --- a/docs/prompts/3-design-ui.md +++ /dev/null @@ -1,16 +0,0 @@ -# Context -You are an expert UX Designer your role is to work with the product owner to generate a custom UI components. -We're in design mode. We're not going to be building any backend functionality or business logic. We're just going to use dummy JSON in order to mock up the prototype of our mini app and show the intended behavior. - -# Inputs -1. Product Brief -2. Feature Plan -3. User Chat - -# Instructions -1. Process the product input documents if one is not provided ask for one -2. Ask questions about the use case / user story if it's unclear to you -3. Generate 3 approaches for UI/UX. Use natural language descriptions or diagrams. Don't use code yet. -4. Ask the product owner to confirm which one they like or amendments they have -5. Proceed to generate the UI design mockups / prototypes. No logic. - diff --git a/docs/prompts/4-review-code.md b/docs/prompts/4-review-code.md deleted file mode 100644 index 7d34255..0000000 --- a/docs/prompts/4-review-code.md +++ /dev/null @@ -1,13 +0,0 @@ -We just implemented the feature described in the attached plan. - -Please do a thorough code review: -1. **Plan implementation**: Make sure that the plan was correctly implemented. -2. **Bug detection**: Look for any obvious bugs or issues in the code. -3. **Data alignment**: Look for subtle data alignment issues (e.g. expecting snake_case but getting camelCase or expecting data to come through in an object but receiving a nested object like {data:{}}) -4. **Code complexity**: Look for any over-engineering or files getting too large and needing refactoring -5. **Style consistency**: Look for any weird syntax or style that doesn't match other parts of the codebase -6. **Architecture compliance**: Verify client-server separation (no direct service imports in client code) and proper data flow (Hook → API Route → Service → External API). Check @docs/planning/coding-principles.md for more coding guidelines. -7. **Design system adherence**: Check semantic color usage, Typography component usage, and mobile-first responsive patterns. Check @docs/planning/design-system.md for more design guidelines. -8. **File structure**: Ensure components are pure UI (data via props only), hooks handle data fetching, and services contain business logic. Check @docs/planning/file-structure.md for more detailed guidelines. - -Document your findings in docs/features/_REVIEW.md unless a different file name is specified. \ No newline at end of file diff --git a/docs/prompts/5-merge-feature.md b/docs/prompts/5-merge-feature.md deleted file mode 100644 index 59b3606..0000000 --- a/docs/prompts/5-merge-feature.md +++ /dev/null @@ -1,13 +0,0 @@ -# Merge Feature - -After feature implementation and code review are complete: - -1. **QA Testing**: Generate and execute a testing checklist focused on core functionality. Run all available automated tests. Only ask user to test what cannot be executed by an agent. -1. **Commit & Push**: Commit all unstaged changes and push to current branch, using GitHub CLI commands. -2. **Version Management**: Bump version if needed (see .cursor/rules/versioning.mdc). Recommend a type of bump (minor or patch) but ask for user to confirm. -3. **Changelog Verification**: Verify Notion changelog entry was created, trigger if not (see .cursor/rules/changelog.mdc) -4. **Create PR**: Create pull request (using GitHub CLI) with both a brief feature description (write for users) and implementation details for technical internal review. -5. **Write Docs**: After the PR is merged, check if the Notion changelog needs update and ask the user to use the docs/prompts/commands/write_docs.md prompt. -6. **Linear Issue**: Update the Linear issue (ask user for the URL if needed) with a brief summary of what was implemented and add links to the GitHub PR and Notion changelog entry. - -Document your findings in docs/features/_MERGE.md unless a different file name is specified. \ No newline at end of file diff --git a/docs/prompts/6-write-docs.md b/docs/prompts/6-write-docs.md deleted file mode 100644 index 3effc52..0000000 --- a/docs/prompts/6-write-docs.md +++ /dev/null @@ -1,23 +0,0 @@ -You are the developer who implemented a new feature that has it's plan and review notes attached. You also have access to the newly implemented code. Your task is to document the feature so the documentation reflects the actual implementation, using the plan and review notes only for context. - -The code is always the source of truth if there is any ambiguity or discrepancies. - -Update or add documentation in these areas: - -- Code comments – function/method/API documentation for IDEs, inline comments only where the purpose is unclear. -- Main documentation set (e.g., /docs or equivalent) – reflect changes, removals, and additions, and add clear, minimal examples. -- New files – only when the feature is large enough to justify them. - -Rules: -1. Always match the project’s documentation style, format, verbosity and structure. -2. Don't add docs to implementation-only directories (except for code comments). -3. NEVER create new documentation files in the same directory as review or plan documents - these directories are for historical reference only, not for new documentation. -4. Avoid redundancy unless it improves usability. -5. Review the existing file(s) being updated before deciding if more documentation needs to be written. -6. Don't document tests unless the user specifically instructs you to. - -Ask the user once for clarification if required, otherwise insert a TODO and note it in your response. - -Output: - -All new and updated documentation updated in the codebase, written in single edits where possible, using the correct format for each type of file. diff --git a/docs/prompts/README.md b/docs/prompts/README.md deleted file mode 100644 index 07cc063..0000000 --- a/docs/prompts/README.md +++ /dev/null @@ -1,51 +0,0 @@ -# Overview -This folder includes prompts that should be copy/pasted into a docs/commands folder and then used by tagging them in the chat (e.g. @plan_feature.md) and providing additional context such as the description of your feature. - -## Workflow -- New projects: - - Define a product brief (business) - to reference regardless of feature - - Embed tech guidance into .cursorrules - - Use a starter kit -- Building features: - - @plan_feature command - - review the plan - - Phases - - @code_review command - - Read through review - - Select fixes to implement - - Manually test - - Confirm code & merge - - - -# Example Use -## Create Brief -Used for establishing the bigger picture context of what this project is about which can be helpful to plan new features. -``` -@create_brief.md - -We are building an application to help dungeon masters plan their D&D campaigns and it's going to be called Dragonroll. It will include a variety of different tools, such as a random map generator and bc generator, loot generator and so on. We will use ai and allow the dungeon master to input certain prompts or use the tools directly. -``` - -## Plan Feature -Used to create a technical plan for a new feature. Focuses on the technical requirements - NOT product manager context bloat or overly specific code details. -``` -@plan_feature.md - -We want to add a new page that is going to be our NPC generator. To implement this, we are going to use the open ai api to generate the description of the npc as well as a name And we'll also generate an image for the npc using the open ai gpt-image-1 model. -``` - -## Code Review -Used to review the successful completion of a plan in a separate chat (and yes, it's this minimal) -``` -@code_review.md -@0001_PLAN.md -``` - -## Documentation Writing -Used to create comprehensive documentation for the plan, review, and implementation. -``` -@write_docs.md -@0001_PLAN.md -@0001_REVIEW.md -``` \ No newline at end of file diff --git a/docs/prompts/learn to code/LearnToCode.md b/docs/prompts/learn to code/LearnToCode.md deleted file mode 100644 index dddb94a..0000000 --- a/docs/prompts/learn to code/LearnToCode.md +++ /dev/null @@ -1,207 +0,0 @@ -# Prompts for Learning to Code with AI - -## Introduction - -Use these prompts to get started learning how to code from scratch or simply to have AI write and modify code for you (via tools such as Cursor, Windsurf, and VS Code Copilot). This set of prompts should help you build your understanding of practical software engineering skills and concepts. - -At the bottom of this doc is a glossary of high-level terms that you may want to plug into the prompts to learn more. - -**Important note**: you ***need*** to use a high-quality model such as **Claude Sonnet 3.5** to make this work. Using GPT-3.5, Llama, or other similar models will only leave you frustrated and stuck. High-end models will generate much better code and explain things much more clearly (and correctly!). Also, do not be deceived by benchmarks - models such as OpenAI o3 may perform exceptionally well on coding benchmarks but are not necessarily the best choice for real-world coding. - -## Exploring Concepts - -- **Starter Prompts** - - What is [X] / How does [X] work / What does [X] mean? How do I use [X]? `<--- simple but super effective` - - I am a new developer learning to code. Please help me create a basic [app idea] web app using the MERN stack - - I am a new developer learning how to code. Please explain what [X] is and what role it plays in building software. - - What are the alternatives to [X]? When and why would I use them? - - I am a new developer interested in understanding the difference between [X] and [Y]. Could you explain? - - In what scenarios would I choose [X] over [Y]? Please explain and provide examples. - - Please explain what each line in this code does: ```[paste the code]``` - - How do you [accomplish certain task]? Answer with a high level explanation and specific steps. - -- **Follow-up Prompts** - - Please rephrase this in a few simple sentences and include an example that would be really easy to understand. - - I still don't get it; can you explain it in a simpler or different way - - How can I use this? / What do I do with this? / Where do I put this? - - What should I do next? / How can I build on this? / Are there any other ways to do this? - - Are there any concerns or tradeoffs with this approach? - - [Open a new Chat and start over] ```<--- good when AI gets stuck rehashing the same ideas``` - -**Note**: Remember to always give the LLM (AI) the relevant context, whether it is the code you are investigating or your relative understanding and experience working with a certain technology. - -## Writing Code - -- **Planning & Design** - - I want to build [feature]. Here's how it should work: [list requirements] - - What technologies would you recommend for building [feature]? - - Let's use [tech stack]. Can you help design the solution before we implement? - -- **Implementation** - - Please create [feature] using [technology list] - - Here's some working sample code to follow: ```[code]``` - - Please implement the following requirements: - 1. [Requirement #1] - 2. [Requirement #2] - 3. [Requirement #3] - -- **Modifying Code** - - I have this code: ```[code]```. Please modify it to [do X]. - - Please refactor this code to keep files under 300 lines: ```[code]``` - - Please add error handling to this code: ```[code]``` - - That code doesn't work because it also needs to [do X]. Can you modify it to do that? - -- **If working outside of a code editor tool** - - I had to make a change to that code so the latest code is: ```[code]``` - - Please state the *full* code in your response - -## Code Quality - -- **Reviews and Improvements** - - Can you review this implementation and suggest any improvements? - - Are there any edge cases we haven't considered? - - How can we make this code more secure and performant? - - Can you check if this is following best practices for [technology]? - - What potential security vulnerabilities should we address? - -- **Documentation** - - Please add clear comments explaining this code - - Can you create documentation for this feature in our README? - - Please explain this code's functionality for new developers - - Can you document the expected inputs and outputs? - -## Troubleshooting - -- **Basic Troubleshooting** - - I tried to run that but got this error: ```[error]``` in the ```[where you saw the error]``` - - It's still not working; what should I check to make sure I am doing this the right way? - - I got this error: ```[error]```. Is there a different way we can do this to avoid this error? - - I tried [X, Y, Z] but it is still not working. Any other ideas? - -- **Advanced Troubleshooting** - - Please add logs throughout this code so we can track exactly what's happening (The Beaver Method): ```[code]``` - - Here are the logs from running that code: ```[logs]``` Can you help me understand where things went wrong? - - Let's try a radically different approach to solving this problem - - Can you take a step back and explain exactly what this code is doing right now? - - Here's a screenshot of what's happening: [screenshot] - -## Learning Strategies - -- **Building Understanding** - - I understand [concept] but am unclear about [concept]. Can you connect these? - - Can you explain this at a high level first, then break it down? - - Please show me some examples of how this works in practice - - How would you architect a [type of app]? What are the key considerations? - -- **Technology Deep Dives** - - What are the core components of [technology]? - - How does [technology] fit into the bigger picture of software development? - - Can you show me a simple example of [technology] in action? - - What are the most important concepts I should understand about [technology]? - -## Glossary / Terminology -These are various terms that you might not be familiar with but can act as starting points for learning with AI. Ask ChatGPT or Claude about these concepts to start building an understanding of how they all fit together. Feel free to incorporate these into your prompts to improve the quality - -### Practical Terms (web development) -- **Frontend:** The part of a website or web application that users interact with directly in their web browsers. It includes the design, layout, and some client-side logic of web pages. -- **Backend:** The server-side logic of a web application, dealing with data management, authentication, server logic, and application functionality that users don't directly interact with. -- **Server:** A physical or virtual machine (ultimately just a computer) that runs the backend code and serves the frontend to users. It processes requests, runs the application's backend logic, and manages resources. -- **Environment:** The setup or context in which an application or development tool runs. In real-world settings, there will typically be a development, testing / staging, and production environments, each with its own configurations and purposes. Your own computer would be categorized as your "local environment". -- **API (Application Programming Interface):** A part of the backend server that exists to enable different parts of your software to communicate with each other. An API typically consists of 'endpoints' that handle specific requests to the backend server. -- **Database:** A backend component used for long-term data storage. Databases allow for secure data retrieval, insertion, updates, and deletion. -- **Authentication:** The process by which an application verifies the identity of a user, typically through login credentials, ensuring that users are who they claim to be. -- **Authorization:** After authentication, the application determines what resources and operations the authenticated user has permission to access and perform within an application. -- **Framework:** A comprehensive set of tools and libraries designed to simplify the development process of software projects by providing a structured foundation to build upon. -- **Library:** A collection of pre-written code that developers can utilize without having to write code from scratch. Libraries typically server a specific purpose, such as integrating with a particular software or implementing commonly used logic. -- **Package Manager:** A tool that automates the process of installing, updating, configuring, and removing packages/libraries from a computer in a consistent manner. -- **Component:** A reusable element in UI design OR a modular unit in software architecture, each with its own functionality. -- **CDN (Content Delivery Network):** A network of servers distributed across different locations that delivers content (files) efficiently to users based on their geographical location. -- **DNS (Domain Name System):** Essentially the phonebook of the Internet, translating human-friendly domain names (like www.example.com) into IP addresses that computers use to identify each other on the network. -- **Proxy:** A server that acts as an intermediary for requests from clients seeking resources from other servers, providing various functionalities such as load balancing, privacy, or security. -- **Domain:** The name that identifies a website on the Internet. It's part of the URL that allows users to easily find and access websites. -- **HTTP (Hypertext Transfer Protocol):** The foundational protocol used by the World Wide Web, defining how messages are formatted and transmitted, and how web servers and browsers should respond to various commands. -- **Cookies:** Small pieces of data sent from a website and stored on the user's computer by the user's web browser while the user is browsing, used to remember information about the user for their next visit. -- **Sessions:** A way to store information across multiple page requests for a particular user, enabling persistence of state across the web application. -- **Service:** A function or set of functions provided by one part of a software system to others, focusing on accomplishing specific tasks. Typically a specific program running somewhere that can be invoked. -- **Microservice:** An architectural style that structures an application as a collection of small, autonomous services, each focusing on a single function or business capability. -- **Container:** Lightweight, standalone, executable software packages that include everything needed to run a piece of software, including the code, runtime, system tools, libraries, and settings. -- **Serverless:** An approach used by cloud web hosting providers to deploy/manage backend servers in a way that enables the real-time dynamic provisioning and allocation of servers. Enables developers to build and run applications and services without thinking about individual servers. -- **Cloud:** Computing services offered over the internet (the cloud), including servers, storage, databases, networking, software, analytics, and intelligence, to offer faster innovation, flexible resources, and economies of scale. -- **Network:** A group of interconnected computers (servers), and devices that can exchange data and resources with each other. -- **ETL (Extract, Transform, Load):** A process in data warehousing that involves extracting data from various sources, transforming it into a suitable format, and loading it into a destination database for analysis or reporting. -- **Data Normalization:** The process of organizing the columns (attributes) and tables (relations) of a database to minimize data redundancy and improve data integrity. -- **Logging:** The process of recording activities and events in a software application or system, which is crucial for debugging and monitoring the application's behavior in development and production environments. -- **Localhost:** The standard hostname for the local computer being used, often for testing software locally (e.g. your computer). -- **Port:** A numerical identifier in networking used to route data to specific programs or services on a computer. - -### Computer Science Terms (relevant for practical use) -- **Algorithm:** A step-by-step procedure or set of rules designed to perform a specific task or solve a particular problem. -- **Language:** In the context of programming, a language is a set of syntax rules and structures used to write software programs that computers can execute. -- **Executable:** A type of file that contains a program capable of being executed or run as a program in the computer. -- **Function:** A block of organized, reusable code that performs a single action or returns a value. -- **Variable:** A symbolic name associated with a value and whose associated value can be changed. -- **Environmental Variable:** A variable that is set outside of the program, typically through the operating system, to pass configuration information to the application. -- **Loop:** A programming construct that repeats a block of code multiple times until a specified condition is met. -- **Infinite Loop:** A loop that continues indefinitely because the loop condition is never satisfied or fails to become false. -- **Call Stack:** A data structure used by programming languages to keep track of active subroutines or functions in a program's execution, where the last function called is the first to be completed and removed. -- **Error:** An issue that interrupts the expected flow of a program, often due to syntax, logic, or resource errors. -- **Stack Trace:** A report showing the sequence of function calls that led to an error or exception, used for debugging. -- **Conditional Statement:** A programming feature that performs different actions based on whether a specified condition evaluates to true or false. (if / else statement) -- **Recursion:** A programming technique where a function calls itself in order to solve a problem. -- **Syntax:** The set of rules that defines the correct combination of symbols that are considered to be a valid part of the language. -- **Queue:** A collection used to manage items in a sequence where items are added and removed according to specific algorithms, with FIFO (First In, First Out) being the most common, but others like LIFO (Last In, First Out) and priority-based removal are also used, depending on the application's requirements. -- **Runtime:** The period during which a program is running, starting from program execution to program termination. -- **Compilation:** The process of translating code written in a high-level programming language into a machine level language that can be executed by the computer. -- **Data Structure:** Organized ways of storing and organizing data in a computer so that it can be accessed and modified efficiently. -- **Memory:** Refers to the temporary storage used by a computer to run programs and process data. "In memory" signifies that data is stored in the main, directly accessible RAM area. -- **Cache:** A temporary storage area that allows for the fast retrieval of data by storing copies of frequently accessed data items or computations. -- **Async vs Sync:** Asynchronous programming allows a program to do more than one thing at a time, while synchronous programming has tasks run in sequence, causing subsequent tasks to wait until the current task finishes. -- **Dependency:** A piece of software or a module that another piece of software relies on to function properly. -- **Error Handling:** The process of responding to and managing errors in a program, often through the use of try-catch blocks or similar constructs. -- **State Management:** The practice of managing the state of one or multiple user interfaces controls like text fields, OK buttons, etc., in a consistent manner. -- **Serialization/Deserialization:** The process of converting an object into a format that can be stored or transmitted (serialization) and the process of converting that format back into an object (deserialization). -- **Multithreading:** A type of execution that allows a single process to have multiple threads of execution running concurrently. -- **Unit Tests:** Tests that cover the smallest parts of an application, like individual functions or methods. -- **Functional Tests:** Tests that assess the specific functionality of an application or its modules, often involving testing UI interactions or API integrations. -- **Performance:** Refers to how fast a web page or application loads and runs. It is critical to user experience and is influenced by various factors, including server speed, database optimization, and efficient coding practices. -- **Load Balancing:** The distribution of network or application traffic across multiple servers to ensure no single server becomes overwhelmed, improving reliability and availability. - - -### Technologies -- **HTML:** The standard markup language for documents designed to be displayed in a web browser. It forms the structure of web pages. -- **CSS:** A style sheet language used for describing the look and formatting of documents written in HTML, controlling the layout of multiple web pages all at once. -- **JavaScript:** A programming language that allows you to implement complex features on web pages, being the only language that can be executed in web browsers, enabling dynamic content, interactive maps, animated 2D/3D graphics, scrolling video jukeboxes, etc. -- **TypeScript:** JavaScript but with clearly defined data types which make code more resilient and easier to understand (when implemented properly). Works particularly well with AI. -- **Frontend Frameworks**: (e.g. React, Vue, Angular).These are JavaScript frameworks and libraries designed to simplify the development of the user interface (UI) of web applications. React is known for its virtual DOM feature for high performance, Angular for its comprehensive solution including tools for routing, forms, HTTP client, and more, and Vue for its simplicity and progressive nature, making it easily adoptable for parts of existing projects. -- **NodeJS:** An open-source, cross-platform JavaScript runtime environment that executes JavaScript code outside a web browser, allowing for the development of server-side and networking applications. -- **NextJS:** A full-stack JavaScrupt framework that uses server-side-rendering to generate html pages just-in-time. Practically speaking, this enables web crawlers such as Google to properly index pages without loading JavaScript, at the cost of greater implementation complexity. -- **Express:** A minimal and flexible Node.js web application framework that provides a robust set of features for web and mobile applications, making it easy to build single-page, multi-page, and hybrid web applications. -- **Databases**: (e.g. MongoDB, Postgres) MongoDB is a popular NoSQL database known for its flexibility and scalability, while PostgreSQL is a powerful open-source relational database system. The key difference lies in how they store data: relational databases structure data into predefined tables and rows, whereas nonrelational databases store data without a fixed schema, often making them more flexible and scalable for certain types of applications. -- **Docker:** A platform as a service (PaaS) that uses OS-level virtualization to deliver software in packages called containers, allowing developers to package applications with their dependencies and deploy as one package. -- **Git:** A distributed version-control system for tracking changes in source code during software development, enabling multiple developers to work on a project concurrently. -- **Cloud Providers:** (e.g. AWS, Azure, GCP) These services offer a wide range of cloud computing resources and services. AWS (Amazon Web Services) is known for its robust, scalable, and affordable cloud solutions. Microsoft Azure offers a wide range of cloud services supporting various operating systems, databases, and developer tools. Google Cloud Platform provides cloud computing services that run on the same infrastructure Google uses internally for its end-user products. -- **Design System:** (e.g. MUI, ShadCN, Chakra, Bootstrap, Tailwind) A set of standards for design and code along with components that unify both practices. These systems help teams develop digital products faster by making design reusable. -- **Redis:** An in-memory data structure store, used as a database, cache, and message broker. Redis supports data structures such as strings, hashes, lists, sets, sorted sets with range queries, bitmaps, hyperloglogs, geospatial indexes with radius queries, and streams. -- **Websocket:** A communication protocol that provides full-duplex communication channels over a single TCP connection, enabling web servers and clients to exchange data more efficiently, facilitating real-time data transfer and interaction in web applications. -- **GraphQL:** A query language for APIs that allows clients to request exactly the data they need, making it possible to aggregate data from multiple sources with a single request. Generally speaking, this should only be used in specific situations where performance improvements are worth the increased code complexity. -- **Webpack:** A static module bundler for JavaScript applications, which bundles JavaScript files for usage in a browser, yet it is also capable of transforming, bundling, or packaging just about any resource or asset. -- **Nginx:** A high-performance reverse proxy and load balancer that sits "in front" of applications and provides increased security, scalability, and speed for web applications. -- **LLM (Large Language Models):** Advanced AI models capable of understanding and generating human-like text, facilitating tasks such as content creation, code generation, and natural language processing. -- **Flutter:** An open-source UI software development kit by Google used for building natively compiled applications for mobile, web, and desktop from a single codebase. -- **Postman:** A collaboration platform for API development, which simplifies each step of building an API and streamlines collaboration so you can create better APIs—faster. -- **curl:** A command-line tool used for transferring data with URLs. It supports various protocols including HTTP, HTTPS, FTP, and more, making it a versatile tool for testing, downloading files, and making API requests directly from the terminal. -- **Terminal:** A text-based interface to the system, allowing for the execution of commands, scripts, and programs. It provides direct access to the underlying operating system through a command-line interface (CLI), essential for software development, system administration, and troubleshooting. - -- ## Process -- **Version Control:** A system that records changes to a file or set of files over time so that specific versions can be recalled later. It's essential for collaborative development projects. -- **SDLC (Software Development Life Cycle):** A process for planning, creating, testing, and deploying an information system, with phases including requirements analysis, design, implementation, testing, deployment, and maintenance. -- **Testing:** The practice of executing a program or application with the intent of finding errors and verifying that the software meets the specified requirements. -- **Accessibility (a11y):** The practice of making your websites usable by as many people as possible, including those with impairments or disabilities, ensuring all users have equal access to information and functionality. -- **Internationalization (i18n):** The practice of designing software to facilitate easy adaptation to different languages and regions, ensuring global usability. -- **Responsive Design:** A design approach aimed at making web pages render well on a variety of devices and window or screen sizes, ensuring usability and satisfaction across different devices. -- **Deployment:** The process of delivering a software application to a live production environment where it can be accessed by users. -- **Monitoring:** The continuous observation of a software application's operation and performance, often using specialized tools, to ensure it functions as expected and to identify issues as they arise. -- **Code Review:** The process of examining written code by one or multiple developers with the purpose of finding bugs or errors, and improving the quality of the code. -- **Continuous Integration (CI):** A development practice where developers integrate code into a shared repository frequently, preferably several times a day, to catch integration errors quickly. -- **Continuous Delivery (CD):** A software development practice where code changes are automatically built, tested, and prepared for a release to production, enabling rapid and reliable software delivery. -- **DevOps:** A set of practices that combines software development (Dev) and IT operations (Ops), aiming to shorten the system development life cycle and provide continuous delivery with high software quality. diff --git a/docs/prompts/learn to code/ultimate-coding-prompt-guide.md b/docs/prompts/learn to code/ultimate-coding-prompt-guide.md deleted file mode 100644 index 6ec9677..0000000 --- a/docs/prompts/learn to code/ultimate-coding-prompt-guide.md +++ /dev/null @@ -1,349 +0,0 @@ -# AI Coding 101: Ultimate Prompt Guide -This is a companion document to go along with my AI Coding 101 video. This document contains all the prompts discussed in the video - though I suggest you watch the video for all of the additional context and explanation that relates to these prompts and tips. - -You can watch the full video here: - -[![AI Coding 101: Ultimate Prompt Guide](https://img.youtube.com/vi/uwA3MMYBfAQ/0.jpg)](https://youtu.be/uwA3MMYBfAQ) -> 🎥 AI Coding 101: Ultimate Prompt Guide (37 tips) - - -# Writing New Code -#### 1. Specify technologies and frameworks - -**Prompt**: -``` -Please create [app/feature description] using [technology list] -``` - -**Example:** -``` -Create a weather tracking app using React (vite), TypeScript, ShadCN, and Tailwind -``` ---- -#### 2. Choose Popular Technologies - -**Recommendations:** -``` -Frontend: TypeScript, React, Tailwind, ShadCN -Backend: TypeScript, Python, Express.js, FastAPI, Django -Databases: Postgres, MongoDB, Redis -Cloud: Cloud Storage (S3), Supabase Auth, Cloud/Edge Functions -``` ---- -#### 3. Design the solution, then implement with AI - -**Prompt:** -``` -I am building a [feature]. It should work like this: [list of requirements] -We should [implementation tips]. It should also handle these edge cases: [list] -``` - -**Example:** -``` -We’re building a search feature. It should perform the search based on the product title and description. - -Create a new component, SearchBar, and add it to the existing NavBar component. Also, create a new search endpoint in the @server.ts file. - -When no results are found, we should display 'No Results' in place of the product list. -``` ---- -#### 4. Break things down, give the AI a list of tasks - -**Prompt:** -``` -Please implement the following: -1. [Requirement #1] -2. [Requirement #2] -3. [Requirement #3] -``` ---- -## 5. Find the right balance of task scope (not too big or small) - ---- -#### 6. Use examples in your prompts - -**Prompt:** -``` -Please create a [feature] that follows this example: [example]” -``` - -**Example:** -``` -Create a date formatting function. It should work like this: -1.Input: '2024-02-07' → Output: 'Feb 7, 2024' -2.Input: '2024-02-07T15:30:00' → Output: 'Feb 7, 2024 3:30 PM' -``` ---- -#### 7. Provide sample code for the AI to follow - -**Prompt:** -``` -Please create a [feature]. Here is working sample code: [code] -``` ---- -#### 8. Use @Docs and @Web context utilities - -**Prompt:** -``` -Please build a [feature]. Reference the [@Docs / link] docs -``` - -``` -Please build a [feature]. Find the best practices and examples for building this on the [@Web]” -``` ---- -#### 9. Make sure the code is secure and performs well - -**Prompt:** -``` -Please implement [feature]. Make sure to account for any potential security issues. -``` - -``` -We just implemented [feature]. Can you check to make sure that it use the most efficient approach? -``` ---- -#### 10. Proactively check for additional considerations - -**Prompt:** -``` -Are there any additional considerations for building [feature]? -``` ---- -#### 11. Ask the AI to write tests & try Test-Driven Development - -**Prompt:** -``` -Please write the tests for the new feature we just implemented -``` - -**Test-Driven Development:** -``` -We are building [feature]. Please write the tests to cover the following cases: [list]. Once complete, build the actual feature. -``` ---- -#### 12. Have AI generate your documentation - -**Example:** -``` -Please add an explanation of this code to our README -``` ---- -#### 13. Use precise naming - -**Example:** -``` -Please create a new csvParser method and add it to the dataParsers.ts file -``` - ---- -# Modifying Existing Code -#### 14. Keep code organized by asking AI to refactor & simplify - -**Prompt:** -``` -Please refactor the code in [file / function] to split it up into [list of files / functions] -``` - -**Example:** -``` -Please split up dataParser.ts into dedicated files including csvParser.ts, xmlParser.ts, and pdfParser.ts -``` ---- -## 15. Manage and balance the CONTEXT you give to the AI - ---- -#### 16. Tag specific relevant files as context - -**Prompt:** -``` -Please implement [feature]. You’ll need to modify [list of files]. Here are additional files for context: [list of files] -``` ---- -#### 17. Keep your files at 300 lines of code or less - ---- -#### 18. Keep in mind that the full conversation is used as context - ---- -#### 19. Start a new conversation for each new feature - ---- -#### 20. Tell the AI what works well and what needs to be changed - -**Prompt:** -``` -This was a good start. [list of features] are working well but [list of problems] still needs to be fixed. Can you fix that? -``` - -**Example:** -``` -The new search feature is properly calling the API and showing results but it is not properly searching by product description. Can you please fix that? -``` ---- -#### 21. Ask AI to find edge cases or bugs - -**Prompt:** -``` -Are there any edge cases we should consider or handle? -``` ---- -#### 22. Ask AI to review the code - -**Prompt:** -``` -Now that we have finished building [feature], can you do a full review of the implementation and the new code? -``` ---- -#### 23. Ask AI about what the current code does - -**Prompt:** -``` -How does the code in [@file] work? Give a high level overview -``` - -``` -How does the [function] work? Give a detailed description” -``` - -**Example:** -``` -What does the code in @serverComm.ts do? How does it handle authentication? -``` ---- -# Troubleshooting -#### 24. Be specific about what is not working (and what is) - -**Prompt:** -``` -When I do [X], I see [Y], but when I do [Z], it seems to work. -``` - -``` -Right now the [feature 1] is working correctly but [feature 2] is failing [failure description]. Can you fix that? -``` - -**Example:** -``` -The buttons are visible now but when I click them nothing seems to happen. Can you fix that? -``` ---- -#### 25. Share screenshots to show what is wrong - -**Example:** -``` -The layout is still incorrect. Please see [@screenshot] and note how the sidebar is not properly expanding. -``` ---- -#### 26. Share the exact errors - -**Prompt:** -``` -It’s still failing - here are the errors: [full error logs] -``` ---- -## 27. The Beaver Method -The beaver method is a troubleshooting approach that works by asking AI to add logs throughout the code that you are troubleshooting, running the software, and feeding the logs back into the AI so that it can troubleshoot with all the relevant runtime context. - -**Step 1 Prompt:** -``` -Please add logs at every step of the process to make it easier to troubleshoot and figure out where the problem is. -``` - -**Step 2 Prompt:** -``` -I ran the process and here is the result: [full logs generated from step 1] -``` ---- -#### 28. Ask AI to explain the code -Similar to #23 but in the context of troubleshooting to help bridge the disconnect between developer expectations and the way the code actually works (which the developer currently perceives as incorrect). - -**Example:** -``` -This code doesn’t convert dates correctly. Can you explain how it works? -``` ---- -#### 29. Ask AI to use a "radically different approach" - -**Prompt:** -``` -This still isn’t working. Let’s try a radically different approach. -``` ---- -## 30. Know when to stop asking AI and read the code yourself - ---- -# Learning To Code - -The following tips match what was covered in the AI Coding 101 episode, but the [Learn To Code](https://github.com/VoloBuilds/prompts/blob/main/LearnToCode.md) page contains more detailed tips for learning to code specifically including a **technology glossary** that can help guide your exploration. - -#### 31. Tell AI to keep it simple + that you are a new dev - -**Example:** -``` -I am learning how to code. Can you simply explain how the frontend connects to the backend? -``` ---- -#### 32. Ask AI to explain code "line by line" - -**Prompt:** -``` -Please add comments explaining [function] line by line -``` - -**Example:** -``` -I am learning how to code. Can you explain the getContactDetails function line by line? -``` ---- -#### 33. Ask AI to explain specific technologies & concepts - -**Prompt:** -``` -Can you explain how [concept] works? What does [technology] do? -``` - -**Example:** -``` -I'm a new dev. Can you explain what databases are for, when I should use them, and what Postgres is specifically? -``` ---- -#### 34. Ask AI how to build something - -**Prompt:** -``` -I want to build a [app/feature]. How would you approach this problem from a technical perspective? -``` - -**Example:** -``` -I want to build a chat app. How would you architect this and what considerations do we need to take into account? -``` ---- -#### 35. Ask AI to show you examples - -**Prompt:** -``` -Can you show me a working example of a [concept] and explain it? -``` - -**Example:** -``` -I am learning to code and want to understand how objects work. Can you create some examples and explain them? -``` ---- -#### 36. Tell the AI what you already know vs what is unclear - -**Prompt:** -``` -I know how [concept] works but can you explain how it relates to [concept 2]? -``` - -**Example:** -``` -I have an API and understand how requests come in but can you explain how I could add authentication to my endpoints? -``` ---- -### 37. Focus on learning and understanding core concepts - ---- diff --git a/docs/temp/.gitkeep b/docs/temp/.gitkeep deleted file mode 100644 index e69de29..0000000 From a26ce089ec3fffe9b1aa65f0600113494665f920 Mon Sep 17 00:00:00 2001 From: macedo Date: Wed, 21 Jan 2026 15:35:06 +0700 Subject: [PATCH 2/3] docs: update default reviewers in create-pr documentation - Added @0xleal as a default reviewer alongside @simaonogueira101 in the create-pr instructions. --- docs/commands/create-pr.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/commands/create-pr.md b/docs/commands/create-pr.md index 9241326..25fd31b 100644 --- a/docs/commands/create-pr.md +++ b/docs/commands/create-pr.md @@ -22,7 +22,7 @@ Create a well-structured pull request with proper description, labels, and revie 4. **Set up PR** - Create PR with descriptive title - Add appropriate labels (by default should be "talent-app", but ask user to confirm) - - Assign reviewers (by default assign to @simaonogueira101, but ask user to confirm) + - Assign reviewers (by default assign to @simaonogueira101 and @0xleal, but ask user to confirm) - Make me (@filmacedo) the Assignee - Link related issues From a9cd1661f9ebb3c0f242f2b97a0ff90444d6d6de Mon Sep 17 00:00:00 2001 From: macedo Date: Thu, 22 Jan 2026 17:55:34 +0700 Subject: [PATCH 3/3] docs: add push/sync changes section to commit documentation - Included instructions for pushing changes to the remote branch after committing. - Added confirmation steps to ensure successful push. --- docs/commands/commit.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/commands/commit.md b/docs/commands/commit.md index e2cb984..681a44c 100644 --- a/docs/commands/commit.md +++ b/docs/commands/commit.md @@ -27,6 +27,11 @@ You are tasked with creating git commits for the changes made during this sessio - Create commits with your planned messages - Show the result with `git log --oneline -n [number]` +5. **Push/sync changes:** + - After committing, push the changes to the remote branch + - Use `git push` (or `git push -u origin ` if the branch doesn't have an upstream) + - Confirm the push was successful + ## Important: - **NEVER add co-author information or Claude attribution** - Commits should be authored solely by the user