Deco Full Analysis

2. BLOCKS_DIAGNOSTICS.md

A human-readable diagnostics report from block validation:

• Summary metrics - Total files, valid %, errors, unused counts
• Critical issues - Top errors grouped by root cause with impact assessment
• Schema errors - Tables of sections/loaders/actions with type mismatches
• Unused code inventory - Categorized lists for cleanup review
• Prioritized recommendations - Actionable fix suggestions
• Re-run commands - How to regenerate the report

3. validation-report.json

Structured JSON report for programmatic use:

• Timestamps and project metadata
• Summary counts (sections, errors, warnings, unused)
• Detailed error list with file, line, property, message
• Full unused files list

4. README.md Updates

If the README is outdated or missing key info:

• How to run the site locally
• Environment setup
• Key commands
• Link to AGENTS.md

Workflow

1.  Analyze deno.json → Framework versions, dependencies, apps
2.  Analyze .deco/blocks/ → Page configurations, key blocks
3.  Map page navigation → How pages link together
4.  Identify lazy sections → Find Rendering/Lazy.tsx wrappers
5.  Analyze loaders/ → Custom data loading
6.  Audit cache headers → Check for `export const cache`
7.  Analyze sections/ → Custom UI components
8.  Analyze actions/ → Custom mutations
9.  Run block validation → Generate validation-report.json
10. Generate BLOCKS_DIAGNOSTICS.md → Human-readable diagnostics
11. Search Deco docs → Understand patterns used
12. Check git log → Top committers
13. Generate AGENTS.md → Comprehensive guide with all sections
14. Update README.md → Quick start, run commands

Tools Used

Code Analysis (file system)

• Read deno.json for dependencies and versions
• Read .deco/blocks/*.json for page configurations
• List sections/, loaders/, actions/ directories
• Read key component files

Deco Documentation

SearchDecoCx({ query: "blocks sections loaders" })

Use this to understand Deco patterns and concepts.

Git Analysis

git log --format='%an' | sort | uniq -c | sort -rn | head -10

Find top committers (code owners).

Key Files to Analyze

Framework Detection

Fresh Stack (SSR + Islands)

// deno.json
{
  "imports": {
    "@deco/deco": "jsr:@deco/deco@...",
    "preact": "npm:preact@...",
    "$fresh/": "..."
  }
}

• Uses islands/ for interactive components
• Uses routes/ for pages
• Sections render on server

HTMX Stack

// deno.json
{
  "imports": {
    "@deco/deco/htmx": "..."
  }
}

• Uses HTMX for interactivity
• Sections can have hx-* attributes

Understanding Page Blocks

Page blocks in .deco/blocks/pages-*.json define which sections appear on each page:

{
  "name": "Home (principal)",
  "__resolveType": "website/pages/Page.tsx",
  "sections": [
    { "__resolveType": "site/sections/Header/Header.tsx" },
    { "__resolveType": "website/sections/Rendering/Lazy.tsx", 
      "section": { "__resolveType": "site/sections/Product/ProductShelf.tsx" }
    }
  ]
}

Key patterns:

• site/sections/* - Custom sections in the repo
• website/sections/* - Sections from website app
• Rendering/Lazy.tsx - Lazy-loaded sections
• Rendering/Deferred.tsx - Deferred sections

App Analysis

Apps in Deco provide loaders, sections, and integrations. Check deno.json:

{
  "imports": {
    "apps/": "https://cdn.jsdelivr.net/gh/deco-cx/apps@...",
    // or forked
    "apps/": "https://cdn.jsdelivr.net/gh/OrgName/deco-apps@..."
  }
}

Common apps:

• apps/vtex/ - VTEX integration
• apps/shopify/ - Shopify integration
• apps/wake/ - Wake integration
• apps/website/ - Core website features
• apps/analytics/ - Analytics

Custom Code Analysis

Custom Sections

sections/
├── Header/
│   └── Header.tsx      # Custom header
├── Product/
│   ├── ProductShelf.tsx
│   └── ProductCard.tsx
└── Footer/
    └── Footer.tsx

Custom Loaders

loaders/
├── search/
│   └── intelligenseSearch.ts  # Custom search
├── product/
│   └── productDetails.ts
└── getUserGeolocation.ts

Custom Actions

actions/
├── cart/
│   └── addToCart.ts
└── newsletter/
    └── subscribe.ts

AGENTS.md Template

# AGENTS.md - [Site Name]

## Quick Reference

| Item | Value |
|------|-------|
| Framework | Deco + Fresh |
| Deco Version | @deco/[email protected] |
| Platform | VTEX / Shopify / Wake |
| Apps Version | apps@commit-hash |

## How to Run

\`\`\`bash
deno task dev
# or
deno task start
\`\`\`

## Architecture

### Stack
- **Framework**: Deco with Fresh (SSR + Islands)
- **Platform**: VTEX IO
- **CDN**: Deco Edge

### Key Pages
| Page | Block | Route | Custom? |
|------|-------|-------|---------|
| Home | pages-Home-123 | `/` | Yes |
| PDP | pages-PDP-456 | `/:slug/p` | Yes |
| PLP | pages-PLP-789 | `/category-slug` | Yes |
| Search | pages-Search-101 | `/s` | Yes |

### Navigation Flow

\`\`\`
Home (/)
  ├── Search (/s) ───────────────────┐
  ├── Category (PLP) ────────────────┤
  │     └── Subcategory ─────────────┤
  └── Product Cards ────────────────→┴─→ PDP (/:slug/p)
                                           ├── Add to Cart → Minicart
                                           └── Buy Now → Checkout
\`\`\`

### Lazy Loading Map

Which sections are lazy-loaded on each key page:

| Page | Lazy Sections | Above Fold |
|------|---------------|------------|
| Home | ProductShelf, InstagramPosts, FAQ | HeroBanner, Carousel |
| PDP | Reviews, BuyTogether, SimilarProducts | ProductInfo, Gallery |
| PLP | ProductShelf (pagination) | Header, Filters |

### Caching Inventory

| Loader | Cache | TTL | Notes |
|--------|-------|-----|-------|
| `loaders/search/intelligenseSearch.ts` | ❌ None | - | Should add SWR |
| `loaders/product/buyTogether.ts` | ✅ SWR | 5min | Good |
| `loaders/getUserGeolocation.ts` | ❌ None | - | Should cache per session |
| `vtex/loaders/categories/tree.ts` | ❌ None | - | High volume, needs cache |

### Custom Code
| Type | Count | Examples |
|------|-------|----------|
| Sections | 15 | ProductShelf, CustomHeader |
| Loaders | 8 | intelligenseSearch |
| Actions | 3 | addToCart |

## Critical User Journeys

### 1. Browse & Purchase
\`\`\`
Home → Search/Category → PDP → Add to Cart → Checkout
\`\`\`

### 2. Direct Search
\`\`\`
Home → Searchbar → Search Results → PDP → Add to Cart
\`\`\`

### 3. Account Access
\`\`\`
Any Page → Login → Account Dashboard → Orders/Wishlist
\`\`\`

## Debugging Tips

### Common Issues

| Issue | How to Debug |
|-------|--------------|
| Section not rendering | Check `.deco/blocks/pages-*.json` for `__resolveType` |
| Loader returning empty | Add `console.log` in loader, check browser devtools |
| Slow page load | Check lazy sections with `?__d` debug flag |
| Cache not working | Verify `export const cache` in loader file |
| VTEX errors | Check VTEX account in `.deco/blocks/vtex.json` |

### Useful Debug Commands

\`\`\`bash
# Check which loaders are called on a page
curl -sI "https://site.com/page?__d" | grep server-timing

# Find sections with a specific loader
grep -r "loaderName" .deco/blocks/

# Check for missing cache headers
grep -L "export const cache" loaders/**/*.ts
\`\`\`

### Performance Flags

- `?__d` - Shows server timing with loader breakdown
- `?__d=verbose` - Extended debug info
- Check `/deco/render` calls in Network tab for lazy sections

## Block Health

Run `deno task validate-blocks -report validation-report.json` to check for configuration issues.

| Status | Count |
|--------|-------|
| ✅ Valid | 85 |
| ⚠️ Warnings | 3 |
| ⚠️ Unused | 14 |
| ❌ Errors | 8 |

### Sections with Errors
- `sections/Product/NotFound.tsx` (7 errors) - missing required props
- `loaders/SAP/createCase.ts` (9 errors) - type mismatches

### Unused Files (candidates for removal)
- `sections/Product/Wishlist.tsx`
- `sections/Social/InstagramPosts.tsx`
- `loaders/legacy/oldProductLoader.ts`

## Code Owners

| Contributor | Commits |
|-------------|---------|
| [email protected] | 150 |
| [email protected] | 89 |

## Important Files

- `deno.json` - Dependencies and tasks
- `.deco/blocks/` - Page configurations
- `sections/` - Custom UI components
- `loaders/` - Custom data loading

## Common Tasks

### Add a new section
1. Create file in `sections/YourSection.tsx`
2. Export default component with Props interface
3. Add to page via Admin or `.deco/blocks/`

### Modify a page
1. Find the page block in `.deco/blocks/pages-*.json`
2. Edit sections array
3. Or use the Deco Admin UI

### Add caching to a loader
\`\`\`typescript
// loaders/myLoader.ts
export const cache = "stale-while-revalidate";
export const cacheKey = (props: Props) => \`\${props.key}\`;
\`\`\`

Example Output

When you run this skill on an e-commerce site, you'll discover:

• Using Deco + Fresh stack
• Platform integration (VTEX, Shopify, etc.)
• Custom intelligent search loader
• Forked or custom deco-apps
• 50+ custom sections
• Key pages: Home, PDP, PLP, Search, Checkout
• Top contributors and their commit counts

Block Validation (validate-blocks)

Run block validation to ensure JSON configurations match TypeScript Props.

How to Run

Run directly from any deco site directory (no installation needed):

# Validate all sections, loaders, and actions
deno run -A https://deco.cx/validate

# Generate a JSON report for analysis
deno run -A https://deco.cx/validate -report validation-report.json

Optional: Add as a deno task for convenience:

Add to your site's deno.json:

{
  "tasks": {
    "validate-blocks": "deno run -A https://deco.cx/validate"
  }
}

Then run:

deno task validate-blocks -report validation-report.json

What It Validates

1. Type Matching - JSON values match Props interface types
2. Required Properties - All required props are present
3. Unused Files - Sections, loaders, and actions not referenced in any block
4. Extra Properties - Properties in JSON not defined in types (with -unused flag)
5. Anti-Patterns - Dead code and structural issues (see Anti-Patterns section below)

Unused Detection

*Loaders and actions are not auto-removed because they may be imported dynamically.

Sample Output

🔍 Validating sections, loaders, and actions...

✅ sections/Header/Header.tsx - 15 occurrence(s)
⚠️  sections/Footer/Footer.tsx - 1 occurrence(s), 2 warning(s)
❌ sections/Category/CategoryGrid.tsx - 1 error(s)
   - "items": required property missing

═══════════════════════════════════════
📊 SUMMARY
═══════════════════════════════════════
Total sections/loaders/actions: 95
Total occurrences: 284
✅ No issues: 85
⚠️  With warnings: 3
⚠️  Unused: 3
❌ With errors: 4

JSON Report (-report flag)

Generate a structured JSON report for automated analysis:

deno run -A https://deco.cx/validate -report validation-report.json

The report includes:

• summary: Total counts (sections, errors, warnings, unused)
• sectionsWithErrors: Detailed error list with file, line, property, message
• sectionsWithWarnings: Detailed warning list
• unusedSections: List of unreferenced files

Use the report to:

1. Track validation status over time
2. Integrate with CI/CD pipelines
3. Generate AGENTS.md Block Health sections automatically

Diagnostics MD Report

After running block validation with -report, generate a human-readable diagnostics file:

# 1. Run validation and save JSON report
deno run -A https://deco.cx/validate -report validation-report.json

# 2. Generate BLOCKS_DIAGNOSTICS.md from the JSON report

The diagnostics MD should include:

• Summary table - Total files, valid, errors, warnings, unused counts
• Critical issues - Top errors grouped by root cause
• Sections with errors - Table of files with error counts
• Loader/action errors - Separate section for non-section files
• Warnings - Props interface issues
• Unused code inventory - Sections, loaders, actions not referenced
• Recommendations - Prioritized fix suggestions
• How to re-run - Commands to regenerate the report

BLOCKS_DIAGNOSTICS.md Template

# Block Validation Diagnostics - [Site Name]

**Generated:** [Date]
**Tool:** validate-blocks v1.1.0

---

## Summary

| Metric | Count |
|--------|-------|
| **Total files analyzed** | X |
| **Total block occurrences** | X |
| **Valid (no issues)** | X (X%) |
| **With warnings** | X (X%) |
| **Unused files** | X (X%) |
| **With errors** | X (X%) |
| **Total errors** | X |

---

## Critical Issues

### 1. [Root Cause Name] (X errors)

**File:** `sections/Example/Example.tsx`
**Impact:** HIGH/MEDIUM/LOW - Affects X pages

[Description of the issue and root cause]

**Affected Pages (sample):**
- page1.json
- page2.json

**Fix Required:** [Specific instructions]

---

## Sections with Schema Errors

| Section | Errors | Issue |
|---------|--------|-------|
| `sections/Example.tsx` | X | Missing required prop |

---

## Unused Code (X files)

### Unused Sections (X files)

| Section | Notes |
|---------|-------|
| `sections/Unused.tsx` | Consider removal |

### Unused Loaders (X files)

| Loader | Notes |
|--------|-------|
| `loaders/unused.ts` | May be called dynamically |

---

## Recommendations

### Priority 1 - [Issue Name] (HIGH)
[Specific fix instructions]

### Priority 2 - [Issue Name] (MEDIUM)
[Specific fix instructions]

---

## How to Re-run Validation

\`\`\`bash
deno run -A https://deco.cx/validate -report validation-report.json
\`\`\`

Task: Generate Diagnostics MD

When analyzing a site, always generate both files:

1. validation-report.json - For programmatic use
2. BLOCKS_DIAGNOSTICS.md - For human review

The diagnostics MD makes it easier to:

• Share findings with the team
• Track issues in PRs/tickets
• Reference specific errors without parsing JSON
• Prioritize fixes by impact

Cleanup Options

# Remove properties not in Props interface
deno task validate-blocks -rm-vars

# Remove unused section files (with confirmation - type 'yes')
deno task validate-blocks -rm-sections

# Show warnings for extra properties
deno task validate-blocks -unused

# Use custom blocks directory
deno task validate-blocks -blocks /path/to/.deco/blocks

Anti-Patterns Detection

The validator detects structural issues beyond type mismatches:

1. Dead Code (never rule)

Sections with website/matchers/never.ts rule will never execute:

{
  "__resolveType": "website/flags/multivariate/section.ts",
  "variants": [{
    "rule": { "__resolveType": "website/matchers/never.ts" },  // 💀 DEAD CODE
    "value": { "__resolveType": "site/sections/Product/ProductShelf.tsx" }
  }]
}

Impact: Bloats page config, confuses developers, slows admin load. Fix: Remove the entire variant or replace with always matcher.

2. Lazy Wrapping Multivariate (Anti-Pattern)

Lazy should not wrap multivariate - the flag evaluation happens immediately anyway:

{
  "__resolveType": "website/sections/Rendering/Lazy.tsx",
  "section": {
    "__resolveType": "website/flags/multivariate/section.ts",  // ❌ WRONG
    "variants": [...]
  }
}

Why it's wrong: Lazy defers rendering, but multivariate flags are evaluated at request time regardless. If you need lazy loading per variant, the multivariate should wrap Lazy sections:

{
  "__resolveType": "website/flags/multivariate/section.ts",
  "variants": [{
    "rule": { "__resolveType": "website/matchers/always.ts" },
    "value": {
      "__resolveType": "website/sections/Rendering/Lazy.tsx",  // ✅ CORRECT
      "section": { "__resolveType": "site/sections/Product/ProductShelf.tsx" }
    }
  }]
}

Sample Anti-Pattern Output

🚨 ANTI-PATTERNS DETECTED

💀 Dead Code (40 sections with 'never' rule):
   📄 pages-Home.json: 30 dead code section(s)
   📄 pages-BlackFriday.json: 10 dead code section(s)

⚠️  Lazy wrapping Multivariate (5 instances):
   📄 pages-Home.json
      Path: sections.variants[0].value[5]
      Lazy wrapping multivariate is an anti-pattern...

Common Block Corruption Patterns

Exploded Strings

Sometimes strings get corrupted into character-indexed objects:

// ❌ Corrupted
{
  "image": {
    "0": "h", "1": "t", "2": "t", "3": "p", "4": "s",
    "5": ":", "6": "/", "7": "/", ...
  }
}

// ✅ Should be
{
  "image": "https://example.com/image.jpg"
}

Detection: Objects with 50+ numeric keys where values are single characters. Fix Script: Reconstruct string from numeric keys sorted by index.

Arrays as Objects

Sometimes arrays get saved as indexed objects:

// ❌ Corrupted
{
  "items": { "0": {...}, "1": {...}, "2": {...} }
}

// ✅ Should be
{
  "items": [{...}, {...}, {...}]
}

Loader-Injected Props Pattern

When a loader injects props at runtime (like device from ctx.device), use this pattern:

// sections/Product/ProductShelfGroup.tsx

export interface Props {
  shelves: ShelfConfig[];
  /**
   * @hide
   */
  device: "mobile" | "desktop" | "tablet";  // Required with @hide
}

export function loader(props: Props, _req: Request, ctx: AppContext) {
  return {
    ...props,
    device: ctx.device,  // Loader always provides actual device
  };
}

In the JSON block, store a default value (will be overwritten by loader):

{
  "__resolveType": "site/sections/Product/ProductShelfGroup.tsx",
  "shelves": [...],
  "device": "mobile"
}

Why this pattern:

1. @hide prevents the prop from showing in admin UI
2. Prop is required in Props, so TypeScript is happy
3. JSON has a value, so deco admin validation passes
4. Loader overwrites with actual runtime value

Validator divergence: Our script validates against the Props interface. Deco admin may validate against SectionProps<typeof loader> which includes loader return types. If you see admin errors not caught by the script, check for loader-injected props.

Nested Props with Loader-Injected Values

When a section has nested props that reference another component's Props (which includes loader-injected values like device), you must Omit those values:

// ❌ WRONG - ProductShelfProps includes required `device`
export interface ProductShelfTimedOffersConfig {
  type: "ProductShelfTimedOffers";
  props: ProductShelfTimedOffersProps;  // shelfProps.device is required!
}

// ✅ CORRECT - Omit device from nested props
type ShelfPropsWithoutDevice = Omit<ProductShelfProps, "device">;

export interface ProductShelfTimedOffersConfig {
  type: "ProductShelfTimedOffers";
  props: Omit<ProductShelfTimedOffersProps, "shelfProps" | "shelfPropsOffer"> & {
    shelfProps: ShelfPropsWithoutDevice;
    shelfPropsOffer?: ShelfPropsWithoutDevice;
  };
}

Why: The parent component injects device at runtime, but deco admin validates the JSON before runtime. If nested props require device, admin shows validation errors even though the code works.

Add to AGENTS.md

Include block health summary:

## Block Health

| Status | Count |
|--------|-------|
| ✅ Valid | 85 |
| ⚠️ Warnings | 3 |
| ⚠️ Unused | 14 |
| ❌ Errors | 8 |

**Files with errors**:
- sections/Product/NotFound.tsx (7 errors)
- loaders/SAP/createCase.ts (9 errors)

**Unused files** (candidates for removal):
- sections/Product/Wishlist.tsx
- sections/Social/InstagramPosts.tsx
- actions/legacy/oldAction.ts

Optimization Checklists

Based on 105 learnings from real Deco sites, run these checklists during analysis:

Available Checklists

Top Patterns to Check

Loader Optimization (most common):

• Heavy sections wrapped in Lazy (BuyTogether, Reviews, Shelves)
• VTEX simulation set to skip or only1P
• No sync product loaders in Header
• AbortController timeout on external APIs

Image Optimization:

• LCP image has loading="eager" and fetchPriority="high"
• First 4-6 PLP products are eager loaded
• All images use Deco <Image /> component
• SVGs bypass optimization proxy

Cache Strategy:

• Custom loaders have export const cache = "stale-while-revalidate"
• Cache keys are deterministic (no URL params, sorted arrays)
• Common loaders use shared blocks for deduplication

SEO:

• JSON-LD escapes < character
• Every page has SEO section
• Prices have exactly 2 decimal places

Hydration:

• No direct window/document access without IS_BROWSER check
• External widgets wait for load via callback
• No Math.random() for ID generation

How to Use Checklists

1. During analysis: Reference relevant checklists when examining code
2. In AGENTS.md: Include findings table showing pass/fail for each area
3. For recommendations: Use checklist items as specific action items

Example Findings Table (add to AGENTS.md)

## Optimization Audit

| Category | Status | Key Findings |
|----------|--------|--------------|
| Loader Optimization | 🟡 | 3 sections need Lazy wrapping |
| Image Optimization | 🔴 | LCP banner missing fetchPriority |
| Cache Strategy | 🔴 | 5 loaders missing cache config |
| SEO | 🟢 | All pages have SEO section |
| Hydration | 🟢 | No SSR/client mismatches found |
| Asset Optimization | 🟡 | Chat widget loads on all pages |
| Bug Fixes | 🟢 | No critical issues |
| Dependencies | 🟡 | Consider updating to latest apps |

Next Steps After Generating AGENTS.md

1. Review the generated AGENTS.md
2. Run block validation to generate validation-report.json
3. Generate BLOCKS_DIAGNOSTICS.md from the validation report
4. Run through optimization checklists for each category
5. Check if README.md needs updates
6. Identify areas that need documentation
7. Use the performance-audit skill for runtime analysis