> ## Documentation Index
> Fetch the complete documentation index at: https://docs.noisemaker.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Recommendations

> Generate, review, implement, and verify evidence-backed SEO and GEO work.

<Frame caption="Recommendations grouped by lifecycle status.">
  <img src="https://mintcdn.com/auto-gtm/iXt5uMxsbIiTmJfR/images/console-recs.png?fit=max&auto=format&n=iXt5uMxsbIiTmJfR&q=85&s=5a54219196204daf11a0dd6a717ff478" alt="Recommendations grouped by lifecycle status." width="2880" height="1800" data-path="images/console-recs.png" />
</Frame>

A recommendation is a versioned work item with evidence, impact, confidence, effort, drafts, reviews, and an append-only transition history.

## Canonical lifecycle

The only active states are <code>proposed</code>, <code>todo</code>, <code>in\_review</code>, <code>done</code>, and <code>archived</code>.

| Current state | Action          | Next state       | Required evidence                     |
| ------------- | --------------- | ---------------- | ------------------------------------- |
| proposed      | accept          | todo             | Transition request                    |
| proposed      | decline         | archived         | Transition request                    |
| todo          | submit          | in\_review       | Current draft and visibility snapshot |
| todo          | archive         | archived         | Transition request                    |
| in\_review    | verify          | done             | Review evidence                       |
| in\_review    | request changes | todo             | Review evidence                       |
| in\_review    | stale reopen    | todo             | System evidence                       |
| in\_review    | archive         | archived         | Transition request                    |
| done          | reopen          | todo             | Reopen note                           |
| done          | archive         | archived         | Transition request                    |
| archived      | restore         | proposed or todo | Prior state history                   |

Restore returns an item archived from an initial proposed or migrated rejected state to <code>proposed</code>. Other archived items return to <code>todo</code>.

Every transition includes the expected status, expected state version, and an idempotency key. A stale client receives a conflict instead of overwriting a newer action.

## Board and drag behavior

The board shows four active columns: Proposed, Todo, In review, and Done. The archive has a separate view. Drag and drop supports pointer, touch, and keyboard interaction, but it applies the same transition rules as explicit buttons.

Moving an item to In review requires a current draft. Moving it to Done requires review evidence.

## Drafts and reviews

Drafts are immutable. A newer draft supersedes the previous current draft without changing its contents.

| Draft kind                      | Purpose                                                       |
| ------------------------------- | ------------------------------------------------------------- |
| <code>social\_draft</code>      | Suggested social copy                                         |
| <code>copy\_prompt</code>       | A prompt and instructions for implementation copy             |
| <code>generated\_content</code> | Full generated content, currently used for eligible blog work |

Version 2 drafts require validation steps. A <code>copy\_prompt</code> must contain a nonempty prompt. The content hash covers content, provenance, evidence, model, prompt version, pricing, and source digests.

Reviews record <code>approved</code>, <code>changes\_requested</code>, or <code>rejected</code>. Compliance-flagged work cannot be submitted without the latest approved review or an explicit approval that creates one.

## Volume generation

Generation has separate SEO and GEO lanes.

| Lane | Target open volume | Per-operation creation cap |
| ---- | -----------------: | -------------------------: |
| SEO  |                 50 |                         20 |
| GEO  |                 20 |                         10 |

Open volume counts Proposed, Todo, and In review. Durable canonical keys prevent duplicate work across generation runs. Candidates are ranked by impact, confidence, and effort.

The SEO lane reserves for a worst case of up to 40 OpenRouter calls because each of 20 candidates can require copy work and eligible blog items can require full content. The current GEO generation job does not reserve provider cost.

Recommendation generation uses the same workspace job slot as measurement, research, and SEO refresh. Start it after the other job has settled.

## Humanizer style contract

All suggested text generated by this subsystem binds to <code>humanizer-v1</code>. The prompt build fails if that contract is missing. Generated copy must:

* Use plain, direct language
* Preserve technical terms that carry meaning
* Avoid unsupported claims, figures, quotations, and citations
* Tie factual statements to the supplied evidence
* Keep validation steps explicit

This is a generation contract, not a substitute for human review.

## Stale work

The system can reopen an In review item when fresh evidence shows that its submitted snapshot is stale. This is a system-only transition and must include the evidence that triggered it.