briefs/
  {brand}/
    _brand.brief.md          ← config + rollup across all locations
    reports/                 ← brand-level rollup reports
    {location}/
      location.brief.md      ← always current, always lean
      reports/               ← weekly, monthly, QBR reports
      scans/                 ← geogrid scans, citation audits, page audits
      drafts/                ← GBP posts, review responses awaiting approval
      alerts/                ← monitoring alerts

First Run Detection

This is the most important section. When a user mentions a specific business and no brief exists, do not proceed with their request yet. Run setup first, then circle back to what they asked for.

Detection

Before doing any work for a specific business, check for an existing brief:

Claude Code: look for briefs/{brand-slug}/{location-slug}/location.brief.md
Claude Project: check Project knowledge base for a brief file for this business
If found: go to Resuming from a Brief
If not found: go to First Run Setup

First Run Setup

Tell the user:

"I don't have a brief for [Business Name] yet. Let me grab a few details so I can track everything going forward. This takes about 2 minutes."

Then ask these questions one at a time, not all at once:

Q1: "What's the primary keyword you want to rank for? (e.g. 'plumber buffalo ny')"

Q2: "What's the website URL?"

Q3: "How far does the service area extend? (e.g. 5 miles, 20 miles)"

Q4: "Are you managing this for a client, or is this your own business?"

If client, ask: "What's the client's email for reports?"
If own business, skip

Q5: "Do you want alerts and reports sent to a Slack channel?" (optional, skip if they say no)

That's it. Don't ask for more than these unless something is genuinely ambiguous.

After Questions

Create brief folder structure:
- briefs/{brand-slug}/{location-slug}/location.brief.md
- briefs/{brand-slug}/{location-slug}/reports/
- briefs/{brand-slug}/{location-slug}/scans/
- briefs/{brand-slug}/{location-slug}/drafts/
- briefs/{brand-slug}/{location-slug}/alerts/
- briefs/{brand-slug}/_brand.brief.md
Populate Identity section from answers and any context already in the conversation
Configure _brand.brief.md approval block from Q4/Q5 answers
Run initial audit automatically, don't ask permission:
- LocalSEOData local_audit
- LocalSEOData business_profile + profile_health
- LocalSEOData geogrid_scan (7x7, primary keyword, stated radius)
- LocalSEOData citation_audit
- LocalSEOData review_velocity + google_reviews
- LocalSEOData competitor_gap
Populate Findings from audit results
Set Next Action to the single highest-priority fix
Offer scheduled task setup:

"Brief created and initial audit done. I found [X critical, Y important issues]. [Top finding in one sentence].

Want me to set up automated monitoring? I can configure weekly ranking scans, review monitoring, GBP change detection, and monthly reports to run automatically."

If yes, go through task list from tasks/README.md, recommend based on audit findings, configure via /schedule If no, proceed with original request
Then return to what the user originally asked for:

"Now let me [original request]..."

For Claude Project / Browser Users

If no filesystem access: run the same conversation and audit, then output the brief as formatted text at the end of setup:

"Here's your brief. Add this to your Project knowledge base so I'll have it next time:" [brief content]

When to Create a Brief (Non-First-Run)

Outside of first run, create a brief mid-session if:

A tool call is about to be made for a business with no brief
User explicitly asks to create one

Do not create briefs for:

General local SEO questions with no specific business
Tool or skill explanations
Single-question answers with no live data

Brief Location

Claude Code / Cowork:

briefs/{brand-slug}/{location-slug}/location.brief.md

Claude Project: Upload brief file to Project knowledge base after creation. Tell user to do this if they haven't.

Updating a Brief (Manual Sessions)

At end of every session:

Session Log. One line: date + what was worked on
Tools Run. Each tool call: date, tool, endpoint, one-line finding
Findings. New issues, categorized Critical / Important / Monitor
Deliverables. Mark completed, add new pending
Next Action. Overwrite with single most important next step

Receiving Scheduled Task Output

When a scheduled task writes an output file:

Read the output file
Add one line to Session Log: [DATE] | {task type} → {one-line finding} → see {output path}
If new Critical findings: update Findings section
Update Next Action if the task surfaced a higher priority than current
Update _brand.brief.md Locations table row for this location

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

Resuming from a Brief

When a user returns to a business:

Read the brief
Read the most recent output file in each subfolder for current state
Summarize in 2-3 sentences: what's been done, key findings, current state
State the Next Action
Ask: "Want to pick up from here, or something specific?"

Do not re-run tools with results in scans/ unless user asks or data is >30 days old.

The Compounding Value

After months of scheduled tasks writing to a brief, the history is queryable:

"Why did rankings drop in March?" reads scans/ for that period
"How have reviews trended this year?" reads reports/ review monitors
"When did this competitor appear?" reads competitor monitors

Never delete output files. Archive if the folder gets unwieldy. The history is the value.

Lessons Flywheel

During every session, manual or scheduled, watch for:

Tool returning data that contradicts a skill file
A pattern emerging across 3+ locations not documented anywhere
GBP, algo, or AI platform behavior differing from documented expectations
A tool endpoint behaving unexpectedly

When observed, surface it explicitly:

"I noticed [X] during this session. This pattern isn't in the skill files. Want me to add it to meta/lessons.md for review?"

Wait for confirmation. Then write the lesson.

Multi-Location Brands

After each location session:

Update that location's row in _brand.brief.md Locations table
Add to Brand-Level Notes only if pattern appears in 3+ locations

Slug Format

Lowercase, hyphens, obvious:

Brand: keystone-insurance, mikes-plumbing
Location: buffalo, downtown-chicago, pittsburgh-pa

brief

Brief Management

Structure