AI Decision Guide
This document maps common scenarios to the correct tools and patterns.
Adding a New Page
- Check
.ai-context.json for route patterns
- Read brand preset from
presets/<client>.json
- Copy structure from
snippets/ similar pages
- Add schema from
templates/ if SEO-relevant
- Follow heading hierarchy from
rules/seo-rules.md
Deploying Changes
ALWAYS follow this sequence:
# Step 1: Deploy to staging
deploy_push({ target: "staging", app_id: "<from .ai-cli.json>" })
# Step 2: Verify on staging URL
# Check: functionality, styling, data loading
# Step 3: If successful, deploy to prod
deploy_push({ target: "prod", app_id: "<from .ai-cli.json>" })
Never skip staging deployment for production changes.
Fixing Brand/Style Issues
- Read
presets/<client>.json for brand rules
- Check
rules/ui-fixes.json for patterns
- Use shadcn MCP for component updates
- 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
- Fetch template:
seo_add_schema({ template: "product", data: {...} })
- Template pulled from Forgejo with current brand
- Inject into page
<head> as JSON-LD script tag
- 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
- Read
.ai-cli.json for database connection info
- Use
supabase_query with parameterized queries only
- NEVER use string concatenation for queries
- Check RLS policies if query fails
Safe Query Pattern:
// 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
- Check
snippets/ for existing similar components
- Follow brand preset for styling
- Use shadcn/ui as base when possible
- Add accessibility attributes (see
rules/ui-fixes.json)
- 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
- Document the fix
- Update
rules/common-fixes.md
- 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/<client>.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:
- Update
context/CHANGELOG.md
- Update
last_updated in _meta section
- 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:
- Check server logs:
abundance docker logs <server> <container> -f --tail 100
- Check health:
abundance health check
- Escalate with full error context
DMleadgen
3cb8d3cb3f