Briefs System — Persistent Engagement State

Briefs are persistent work state containers for local SEO engagements. One brief per location. One brand rollup per multi-location client. Every audit, scan, report, finding, and deliverable accumulates in the brief’s directory structure.

The brief is the index — a lean, scannable summary of current state. Detailed outputs live in subdirectories. The brief points to them.

Directory Structure

briefs/
  {brand-slug}/
    _brand.brief.md            ← Config + multi-location rollup
    reports/                    ← Brand-level aggregated reports
    {location-slug}/
      location.brief.md        ← Current state (kept lean)
      reports/                  ← Weekly, monthly, QBR outputs
      scans/                    ← Geogrid scans, citation audits, page audits
      drafts/                   ← GBP posts, review responses awaiting approval
      alerts/                   ← Monitoring alerts

Slug conventions:

  • Brand slugs: lowercase, hyphenated — keystone-insurance, mikes-plumbing
  • Location slugs: city or neighborhood — buffalo, downtown-chicago, pittsburgh-pa

Location Brief Template

Each location.brief.md follows this structure:

# {Business Name} — {Location}

## Identity
- Business: {name}
- Address: {address}
- Phone: {phone}
- Website: {url}
- GBP: {gbp_url}
- Type: storefront | SAB | hybrid
- Primary category: {category}
- Target keywords: {keywords}
- Service area: {radius} (if SAB)

## Session Log
[DATE] — what was worked on (newest first)

## Tools Run
[DATE] tool → endpoint → one-line summary

## Findings
### Critical
(ranking suppressors, suspension risks)

### Important
(30-60 day priority gaps)

### Monitor
(low-priority, watch items)

## Deliverables
- [ ] pending items
- [x] completed items

## Next Action
Single explicit next step. Updated at end of every session.

The Identity section is set during first-run setup. Everything else evolves over time.

Brand Brief Template

The _brand.brief.md contains configuration and cross-location state:

# {Brand Name} — Brand Rollup
<!-- auto-maintained by agent -->

## Config
approval:
  reviewer: agency
  reviewer_channel: slack
  reviewer_contact: #local-seo-alerts
  client_notify: true
  client_channel: email
  client_contact: contact@client.com
  client_notify_format: summary
  approval_timeout_hours: 48
  timeout_action: archive

alerts:
  review_velocity_drop_pct: 40
  arp_degradation_positions: 2
  solv_drop_points: 10
  new_one_star: true
  gbp_change: true
  lsa_rank_drop_positions: 3
  ai_visibility_drop_points: 15

## Locations
| Location | Last Worked | Critical | Important | ARP | SoLV | Next Action |
|----------|-------------|----------|-----------|-----|------|-------------|

## Brand-Level Notes
(Patterns across 3+ locations — not location-specific)

## Brand Assets
- GBP owner account: {account}
- Primary contact: {contact}
- Tools connected: {tools}
- Reporting cadence: {cadence}

First-Run Workflow

Detection

Before engaging with any business, verify whether a brief exists:

  • Claude Code: Check filesystem path briefs/{brand-slug}/
  • Claude Projects: Search project knowledge base

If absent, proceed to setup. If present, resume from existing brief.

Setup Conversation

Ask five questions sequentially (one at a time):

  1. Primary keyword target — what does this business want to rank for?
  2. Website URL — for on-page analysis and schema detection
  3. Service area radius — defines geogrid scan boundaries
  4. Client vs. owner — determines reporting format and communication style
  5. Slack notifications — optional, configures alert delivery channel

Post-Setup Automation

Immediately run the initial diagnostic suite:

  1. local_audit — comprehensive local presence check
  2. business_profile — GBP profile data
  3. profile_health — completeness and optimization scoring
  4. geogrid_scan — 7x7 grid for primary keyword
  5. citation_audit — NAP consistency across directories
  6. review_velocity — review trend and response rate
  7. google_reviews — recent review content and sentiment
  8. competitor_gap — competitive benchmarking

Populate Findings from results. Identify the single highest-priority issue as Next Action.

Session Maintenance

At the conclusion of every session, update the brief across five dimensions:

  1. Session Log — add date and one-line activity summary
  2. Tools Run — add date, tool name, endpoint, one-line finding
  3. Findings — update categories (Critical / Important / Monitor) based on new data
  4. Deliverables — update completion status
  5. Next Action — set the single highest-priority next step

The brief stays lean. Detail lives in the output files.

Scheduled Task Integration

When automated tasks generate outputs:

  1. Add one Session Log line referencing the output path
  2. Update Findings if Critical issues surface
  3. Refresh Next Action based on new data

Format: [DATE] — {task type} complete → {one-line finding} → see {output file path}

Resuming Sessions

When a user returns to work on an existing client:

  1. Read the existing brief
  2. Scan recent output files in subdirectories
  3. Provide a 2-3 sentence status update
  4. State current Next Action
  5. Ask user preference for continuation direction

Multi-Location Management

  • Update each location’s row in the brand brief only after individual location work
  • Add to brand-level notes exclusively when patterns appear across three or more locations
  • Run portfolio health checks via the brand brief’s locations table

Privacy and Client Data

The briefs/ directory is gitignored by default. Client data — business names, addresses, audit findings, competitive analysis — stays local. Templates and structure are version-controlled. Client data is not.

Learn More

To learn what briefs can do for your local SEO workflow, see the briefs overview.