Competitive Intel Cadence

# Competitive Intel Cadence (P7-B)
 
Purpose: run a lightweight monthly landscape brief that tracks competitor changes and converts them into concrete roadmap/positioning actions.
 
## Scope
 
- Primary SHIP competitors: `71lbs`, `Share a Refund`, `LateShipment.com`, `Sifted (SiftedAI)`.
- Primary TRADE competitors: `Flexport`, `Zonos`, `Avalara`, `Descartes`.
- Optional expansions: add companies from `docs/partners/gtm-pipeline.md` when overlap increases.
 
## Monthly Workflow
 
1. Build source set (release notes, product pages, pricing pages, public announcements).
2. Capture deltas by company:
- product capability changes
- pricing/packaging changes
- GTM/channel movement
3. Publish brief at `docs/partners/competitive-briefs/YYYY-MM.md` using the template.
4. Record implications:
- positioning/message changes
- roadmap pressure or acceleration candidates
- sales enablement updates needed
5. Add next-cycle hypotheses to validate.
 
## Quality Bar
 
- Every non-trivial claim includes at least one source link.
- Confidence is explicit (`high`, `medium`, `low`) per item.
- Unknowns are labeled as unknown; avoid speculative assertions.
- Separate observations from recommendations.
 
## Roles
 
- Owner: GTM/strategy owner (default: Dan).
- Support: engineering for technical feasibility checks on any proposed response.
 
## Output Contract
 
Each monthly brief includes:
 
- executive summary
- delta scoreboard by company
- top implications for RGL8R
- recommendation list (owner + priority)
- next-month watch items
 
## Automation
 
The monthly brief is generated automatically via the mac-mini task-runner.
 
### Components
 
| Component | Location | Purpose |
|-----------|----------|---------|
| Task prompt template | `scripts/templates/p7b-competitive-brief.md.tmpl` | Reusable prompt with `__MONTH__` placeholder |
| Enqueue script | `scripts/enqueue-p7b-brief.sh` | Substitutes month, writes task to `~/tasks/pending/`, guards against duplicates |
| Task runner | `scripts/task-runner.sh` (canonical; deployed to `~/scripts/` on mac-mini) | Picks up `.md` files from `~/tasks/pending/`, runs Claude in a worktree |
 
### Cron Schedule
 
The enqueue script runs on the 1st of each month at 08:00 local time:
 
```cron
# --- Monthly intel cadence ---
# 0 8 1 * * . /Users/dan/.config/rgl8r/cron.env && /Users/dan/scripts/enqueue-p7b-brief.sh
```
 
The task-runner picks up the enqueued task on its next poll cycle (every 30 minutes).
 
### Timeout Configuration
 
The task-runner wraps Claude invocations with `gtimeout` (GNU coreutils). The
timeout is controlled by the `TASK_TIMEOUT_SECS` environment variable (default:
120 seconds). Research-heavy tasks like competitive briefs need more time --
set `TASK_TIMEOUT_SECS=300` in the task-runner's cron entry or invoke manually:
 
```bash
TASK_TIMEOUT_SECS=300 ~/scripts/task-runner.sh
```
 
Note: `TASK_TIMEOUT_SECS` must be set in the task-runner's environment, not the
enqueue script's -- they are separate processes.
 
### Dry-Run
 
To test the pipeline end-to-end without waiting for cron:
 
```bash
# 1. Enqueue a brief for the current month (or override with BRIEF_MONTH)
BRIEF_MONTH=2026-03 ~/scripts/enqueue-p7b-brief.sh
 
# 2. Verify the task file was created
ls ~/tasks/pending/p7b-brief-2026-03.md
 
# 3. Run the task-runner manually (it will pick up the oldest pending task)
~/scripts/task-runner.sh
 
# 4. Check the result
ls ~/tasks/completed/p7b-brief-2026-03.md   # success
ls ~/tasks/failed/p7b-brief-2026-03.md      # failure
cat ~/logs/task-p7b-brief-2026-03-*.log     # full Claude output
```
 
### Failure Handling
 
When a task fails:
 
1. **Task file moves to `~/tasks/failed/`** -- the task-runner moves the `.md` file
   from `running/` to `failed/` on any non-zero exit code.
2. **Slack notification fires** -- the task-runner's `notify()` function sends an
   error-severity message via `~/scripts/slack-notify.sh`.
3. **Log file is written** -- full Claude output is captured at
   `~/logs/task-p7b-brief-YYYYMMDD-HHMMSS.log`.
 
To retry a failed task:
 
```bash
# Option A: Move the failed task back to pending
mv ~/tasks/failed/p7b-brief-2026-03.md ~/tasks/pending/
 
# Option B: Re-run the enqueue script (only works if the failed file is removed first)
rm ~/tasks/failed/p7b-brief-2026-03.md
BRIEF_MONTH=2026-03 ~/scripts/enqueue-p7b-brief.sh
```
 
The duplicate guard checks all four directories (`pending/`, `running/`,
`completed/`, `failed/`), so you must remove or move the existing file before
re-enqueueing for the same month.