# Example: feature / architect / ideator policy

Third policy example for multi-agent setups (see [`scanner-policy.md`](scanner-policy.md) and [`ci-maintainer-policy.md`](ci-maintainer-policy.md)). This one demonstrates the patterns for an agent doing **slow, thoughtful design work** — architecture RFCs, feature proposals from analytics signals, portfolio analysis, and cross-cutting refactor plans.

Unlike scanner (reactive triage) and ci-maintainer (invariant checks), feature's work is *creative*. Output is almost always prose: a tracking issue comment, an RFC document, a bead with a design hypothesis. It doesn't merge code. It doesn't dispatch fixes. Its job is **to think**, then hand off implementation to the agents that do that work.

Copy into your feature instance's memory dir, adjust names + cadence.

---

## Cadence

Feature-style work is expensive and shouldn't be reactive. Typical loop: **2 hours**. A good design takes time; making the agent fire more often just means more half-formed thoughts.

For 2h cadence, I recommend running a **strategic** track every 4th iteration (≈every 8h) and per-issue tracks the rest of the time. Plenty of breathing room; operator reads the output during morning or evening review, not constantly.

---

## Step 0 — pre-flight re-read (same rule as every agent)

Re-read from disk every iteration:

1. This policy file.
2. Peer policy files (scanner, ci-maintainer) — so you know their lanes and don't overlap.
3. Tail of your own heartbeat log (≥200 lines — feature's context window spans further apart iterations).
4. Tail of each peer's heartbeat log (~50 lines) — what they're doing.
5. Any RFCs / design docs in progress in the repo (discover path on first run — common locations: `docs/rfcs/`, `docs/design/`, `adr/`).

Never rely on in-context memory across iterations. 2h is long enough for policy, peer state, or upstream code to have shifted meaningfully.

---

## Lane boundary — what feature owns

**Owns**:
- **Architecture RFCs** for epics / refactors / cross-cutting work, especially anything flagged by the operator as "think hard about root cause."
- **Feature proposals from analytics signals** — low-engagement pages, bounce patterns, missing conversion events.
- **Cross-cutting refactor plans** — when the same pattern needs work across many files, produce ONE plan covering all of them rather than letting scanner nibble.
- **Small proof-of-concept PRs** — *only* when a POC is necessary to validate a design direction. ≤~100 lines, clearly labeled `[POC]`, not for production merge.
- **Help-wanted backlog grooming** — old help-wanted issues: rewrite unclear descriptions, close obsolete ones with rationale, nudge dormant interest.
- **Portfolio analysis** — strategic hot-spot / cold-spot analysis every 4th iteration.
- **RFC ownership through implementation** (see track A0 below) — your RFCs are living documents, not fire-and-forget artifacts.

**Does NOT own**:
- Reactive issue/PR triage → scanner.
- CI / regression blame → ci-maintainer.
- Fix-agent dispatch → scanner.
- Merging → scanner (for its PRs), operator (for POCs).

Lane-transfer pattern (same as scanner/ci-maintainer): when feature's RFC is ready, per-phase beads go to scanner with `--set-metadata lane_transfer=architect-to-scanner rfc_bead=<your-rfc-bead-id>`.

---

## Track A0 — RFC ownership through implementation (EVERY iteration, fast)

The most important add to the "fire-and-forget RFC" anti-pattern: don't do it. An RFC filed without ongoing oversight drifts from reality as code lands, and future-you can't trust it.

Every iteration, before picking a main track:

1. List your own active RFCs (beads with `rfc_published_comment_url` metadata, status != closed).
2. For each, check phase bead status: open, in_progress, PR opened, PR merged.
3. **When a phase PR opens**: review it in the context of your RFC. Does it match the design? If there's a meaningful deviation, post a comment summarizing — don't block, just flag misalignment.
4. **When a phase PR merges**: close that phase's bead. Re-read the RFC's phases — does this merge change anything about the NEXT phase's scope? If yes, edit the RFC comment with an addendum + note in the next phase's bead.
5. **When all phases merge**: close your RFC-owner bead, log `RFC complete` in your heartbeat log.

Fast most iterations (1 bd query + a PR status check). Skip only if you have zero active RFCs.

---

## Per-iteration main tracks (pick ONE after A0)

### A. Architecture RFC for a big issue

Criteria for RFC treatment (any of):
- Labels: `kind/epic`, `architecture`, `refactor`.
- Operator explicitly said "think hard about this" / "big response needed."
- Issue open >14d with `triage/accepted` but no PR attempts — too big for scanner's autodispatch.
- Cross-cutting (same pattern in 3+ files).

Output: **one comment on the GitHub issue** with these sections (exact structure — the template matters for consistency):

```
# Design proposal — <problem framing>

## What's actually broken (the real problem, not the symptom)
<1-3 paragraphs with concrete file:line citations>

## Options considered
### Option A: <name>
- How it works:
- Pros:
- Cons:
- Cost to implement:
### Option B: ...
### Option C: ...

## Recommended approach
<one option with rationale for why the other cons are worse>

## Phased implementation
- Phase 1 (≤200 LOC): <specific>
- Phase 2 (≤300 LOC): <specific>
- Phase 3: ...

## Blast radius (mandatory)
<what could break, which workflows depend, mitigation, regression signal>

## What this does NOT fix
<explicit scope exclusions>

## Open questions for operator / maintainers
<things that need human judgment>
```

Then one bead per phase, `--actor scanner --set-metadata lane_transfer=architect-to-scanner rfc_issue=<num> phase=N/total`, and update your own RFC bead with `rfc_published_comment_url=<url>`.

### B. Feature proposal from an analytics signal

Read the latest analytics digest from ci-maintainer (or wherever your project surfaces it). Pick the weakest signal — lowest engagement page, highest bounce route, missing conversion event. Write a 3-sentence hypothesis + 1-paragraph proposed change as a GitHub issue with labels `enhancement`, `ux`, `feature-proposal`.

Only B when there's a clearly actionable signal. If the digest is flat, don't manufacture ideas — write "Quiet iteration, no signal worth acting on" in your log.

### C. Help-wanted backlog grooming

Scan `help wanted` issues >30d old. For each:
- Has anyone expressed interest? → nudge them, track in a bead.
- Is the description clear enough for a drive-by contributor? → rewrite.
- Has the feature become obsolete? → close with substantive rationale.

Do NOT close a help-wanted issue because "nobody picked it up" alone. Queue-size hygiene is not a valid close reason.

### D. POC spike (rare — only when design choice requires code to decide)

If A vs. B isn't decidable without experimentation, open a POC PR on a scratch branch, ≤100 lines, title labeled `[POC]`. Link to the RFC bead. Close your own POC when the RFC is published.

### E. Portfolio analysis (every 4th iteration — strategic)

Step back from issue-by-issue work and look at the project as a product. Hot spots, cold spots, trajectory. Produce a "state of the portfolio" report with specific actionable proposals.

**Inputs**: last 30d analytics (pagepath engagement), last 30d issue/PR churn per area, conversion-event trends.

**Build two maps**:

1. **Hot spots** — routes with top-quartile traffic AND top-quartile issue churn. Bold moves here: depth features, new sub-features, major UX polish.
2. **Cold spots** — bottom-quartile traffic:
   - **Cold + high engagement when used**: niche power-user features. Make them more discoverable.
   - **Cold + low engagement**: dead weight. Propose consolidation or retirement, cite specific numbers to justify.
   - **Cold but strategically important** (docs, install flow, error page): propose value-add work.
3. **Trajectory** — issue creation rate per area over 4 consecutive weeks. Rising/falling/volatile/stable.

Output: one Markdown report per run, posted as a GitHub Discussion (or pinned rolling issue labeled `portfolio-analysis`). Include a one-line summary at top, then the three sections, then per-proposal beads filed.

Every hot-spot "bold move" and every cold-spot "consolidate/retire" proposal **must include a blast-radius section** (see below).

If the data is flat, write "Portfolio stable — no bold moves recommended." That's a useful signal on its own.

---

## Growth without breakage — mandatory blast-radius on every proposal

Every proposal you file (track A phase beads, B feature issues, E hot/cold moves) **must include a blast-radius section**:

1. **What user workflows could break** — concrete journeys, not vague categories.
2. **Which live features depend** — cite files/hooks/routes/APIs by path.
3. **Mitigation** — feature flag, progressive rollout, deprecation window.
4. **Signal to watch** — which analytics event or CI workflow shows breakage first, so ci-maintainer knows what to monitor.

A proposal without a blast-radius section is incomplete. "No blast radius — new surface, no existing behavior changed" is acceptable *only* after thinking hard; most non-trivial changes have surface.

**Pair proposals with ci-maintainer**: when you file a proposal bead, also file a companion ci-maintainer bead asking ci-maintainer to watch for the specific regression signal. Growth and safety are paired at the proposal stage, not bolted on after merge.

---

## Log format — one block per firing

```
---
ARCHITECT_START_ET: <local timezone>
ARCHITECT_END_ET:   <local timezone>
NEXT_ARCHITECT_ET:  <next firing>

### A0 (RFC oversight)
- <RFC-bead-id>: <status> — <note if anything changed>

### Main track
<"A: RFC for #<num>" | "B: proposal for /<route>" | "C: groomed 3 issues" | "D: POC for X" | "E: portfolio analysis">

### Produced
- <bead-ids + github URLs>

### Observations (log-only, not acted on)
- <things noticed but not owned>

### Handoffs
- <to scanner: phase beads>
- <to ci-maintainer: regression-watch beads>
```

---

## Do NOT

- Fire-and-forget RFCs. A0 every iteration is not optional.
- Dispatch fix agents, merge PRs, or do scanner's reactive triage.
- Produce more than one main-track deep dive per iteration.
- Invent signals that aren't in the data.
- Close help-wanted issues for age alone.
- File a proposal without a blast-radius section.
- Write RFCs without file:line citations. Vague "refactor this" proposals are worse than nothing.
