# AI Decision Guide This document maps common scenarios to the correct tools and patterns. --- ## Adding a New Page 1. Check `.ai-context.json` for route patterns 2. Read brand preset from `presets/.json` 3. Copy structure from `snippets/` similar pages 4. Add schema from `templates/` if SEO-relevant 5. Follow heading hierarchy from `rules/seo-rules.md` --- ## Deploying Changes ### ALWAYS follow this sequence: ```bash # Step 1: Deploy to staging deploy_push({ target: "staging", app_id: "" }) # Step 2: Verify on staging URL # Check: functionality, styling, data loading # Step 3: If successful, deploy to prod deploy_push({ target: "prod", app_id: "" }) ``` ### Never skip staging deployment for production changes. --- ## Fixing Brand/Style Issues 1. Read `presets/.json` for brand rules 2. Check `rules/ui-fixes.json` for patterns 3. Use shadcn MCP for component updates 4. Verify dark mode support if applicable ### Common Patterns: | Issue | Solution | |-------|----------| | Colors not matching | Check CSS variables match preset | | Font not loading | Verify Google Fonts import | | Spacing inconsistent | Use Tailwind spacing scale | --- ## Adding Structured Data 1. Fetch template: `seo_add_schema({ template: "product", data: {...} })` 2. Template pulled from Forgejo with current brand 3. Inject into page `` as JSON-LD script tag 4. Validate with Google Rich Results Test ### Template Selection: | Content Type | Template | |--------------|----------| | Product/Service | `schema-product.json` | | Event | `schema-event.json` | | Business Listing | `schema-local-business.json` | | FAQ Section | `schema-faq.json` | --- ## Database Operations 1. Read `.ai-cli.json` for database connection info 2. Use `supabase_query` with parameterized queries only 3. **NEVER** use string concatenation for queries 4. Check RLS policies if query fails ### Safe Query Pattern: ```javascript // Correct supabase_query({ query: "SELECT * FROM vendors WHERE category = $1 AND active = $2", params: ["photography", true] }) // WRONG - Never do this supabase_query({ query: `SELECT * FROM vendors WHERE category = '${category}'` }) ``` --- ## Creating New Components 1. Check `snippets/` for existing similar components 2. Follow brand preset for styling 3. Use shadcn/ui as base when possible 4. Add accessibility attributes (see `rules/ui-fixes.json`) 5. After creation, update context: ``` context_update({ file: "snippets/components.md", section: "new-components", content: { name: "ComponentName", path: "..." } }) ``` --- ## Handling Errors ### Step 1: Identify Error Type | Error Type | Check | |------------|-------| | Type Error | TypeScript interfaces, props | | Runtime Error | Console logs, stack trace | | Build Error | Dependencies, env vars | | Database Error | RLS policies, query syntax | ### Step 2: Check Common Fixes Look in `rules/common-fixes.md` for known solutions ### Step 3: If New Pattern Found 1. Document the fix 2. Update `rules/common-fixes.md` 3. Run `context_update` to log the change --- ## Context Update Required When | Event | Action | |-------|--------| | New feature added | Update client's SKILL.md | | Bug fix discovered | Add to `rules/common-fixes.md` | | Brand changed | Update `presets/.json` | | New component pattern | Add to `snippets/` | | New API endpoint | Add to `.ai-cli.json` | | Database schema change | Update relevant schemas | ### After ANY context update: 1. Update `context/CHANGELOG.md` 2. Update `last_updated` in `_meta` section 3. Notify user if major change --- ## Tool Selection Quick Reference | Task | Tool | |------|------| | Check MCP connection | `ping()` | | Deploy app | `deploy_push()` | | Add SEO schema | `seo_add_schema()` | | Query database | `supabase_query()` | | Update context files | `context_update()` | | UI components/themes | shadcn MCP | | File operations | filesystem MCP | --- ## Emergency Contacts If unable to resolve: 1. Check server logs: `abundance docker logs -f --tail 100` 2. Check health: `abundance health check` 3. Escalate with full error context