Managing Use Case Pages

Managing Use-Case Pages

You are helping someone ship or update an SEO use-case landing page on the workflow site (comfy.org/workflows/use-cases/<slug>/). The requester may be a content manager, a growth person, or an engineer; they should never need to understand JSON, TypeScript, or the build pipeline. You handle all of that. They contribute facts, judgment, and approval.

The full rules live in site/docs/use-case-page-guide.md. This skill is the procedure; when it says "per the guide", follow that document.

How to interact with the requester

These rules apply to every step below, whether you run interactively (a person in the conversation) or non-interactively (triggered from a Slack thread or a PR comment):

1. Decisions are theirs, mechanics are yours. Never invent a keyword, a clearance, or an app link. Never ask them to write JSON. Site-wide conventions (slug, title, h1 patterns) are presented for correction, not asked as questions; decisions and content require an explicit yes.
2. If you cannot ask the requester directly (no interactive session), post your question where the request came from (the Slack thread or the PR) and stop until a named human answers. Do not proceed on assumptions.
3. Silence is not approval. Every approval point below requires an explicit yes.
4. Never merge a PR, never mark your own PR ready without the requester's go-ahead, and never push extra commits to an approved PR (pushing dismisses approvals; batch fixes into one push).

Entry point A: create a new page

Step 1: Collect the facts

Ask the requester for the keyword's row from the planning source named in the guide's "Where the Facts Come From" section (currently an internal keyword sheet; they paste the row or state the values). You need:

• the keyword (e.g. "ai logo generator")
• the gate value (brand-safety clearance)
• the published workflow / app links for it, if any
• search volume if available (goes in the PR body)

If the keyword has no row, ask whether the SEO owner has cleared it. No confirmed clearance means stop (see Step 2). Record where the facts came from; the PR body will state it.

Also check whether an existing page already serves this keyword: read the keywords.primary and keywords.secondary of every entry in site/src/lib/workflow-pages/use-cases.ts. If one matches, propose extending that page instead of creating a near-duplicate.

Keyword overlap is not the only kind of duplicate, and it is the one that reads clean. Once you know which workflows the new page would show (Step 3), grep those share ids against the same file: if the candidate lead is already another page's appShareId or lead pin, the two pages would front the identical workflow and compete with each other. Propose extending that page instead, and say which one it is.

Step 2: Gate check (hard stop)

If gate is anything other than OK, or clearance cannot be confirmed, stop and tell the requester the keyword needs the brand-safety approver's sign-off first. Additionally run the guide's brand-safety denylist against the keyword yourself and stop on a hit; the build would fail on it anyway, but fail early and explain why.

GATED and GATED-LITE each have their own clearing conditions (guide, "Brand Safety"). Name the outstanding condition rather than saying only "it is gated", and never treat a workflow being publicly browsable on the Hub as evidence that it is cleared for a page.

The same stop applies to an individual pin, not only the page's keyword: a cleared keyword can still pin a gated workflow. Check every candidate pin against GATED_SHARE_IDS in site/src/lib/workflow-pages/use-cases.ts before proposing it, and if one is gated, pin it with its gate value so the intent is recorded but not rendered.

Step 3: Supply check (hard stop on zero)

Find out what the grid would contain before promising a page. Query the live catalog:

HUB_INDEX=$(mktemp)
curl -s 'https://cloud.comfy.org/api/hub/workflows/index?status=approved' -o "$HUB_INDEX"
python3 - "$HUB_INDEX" <<'EOF'
import json, sys, urllib.request
raw = json.load(open(sys.argv[1]))
entries = raw if isinstance(raw, list) else raw.get('workflows', raw)
TAG = 'REPLACE WITH CANDIDATE TAG'
hits = [e for e in entries if TAG in (e.get('tags') or [])]
print(len(hits), 'tag matches')
# The index carries NO reliable app signal; the truth is per workflow. Sweep the
# matches' detail records for workflow_json.extra.linearMode (slow-ish, ~1s each).
apps = []
failed = []
for e in hits:
    sid = e.get('shareId')
    try:
        with urllib.request.urlopen(f'https://cloud.comfy.org/api/hub/workflows/{sid}', timeout=30) as r:
            detail = json.load(r)
        if ((detail.get('workflow_json') or {}).get('extra') or {}).get('linearMode') is True:
            apps.append((sid, e.get('title')))
    except Exception as err:
        failed.append(sid)
        print(' ', sid, 'detail fetch failed:', err)
if failed:
    raise SystemExit(f'{len(failed)} detail fetches failed; retry, do not judge supply from this')
print(len(apps), 'of', len(hits), 'are App Mode')
for sid, title in apps:
    print('  APP', sid, '|', title)
for e in hits[:15]:
    print(' ', e.get('shareId'), '|', e.get('title'))
EOF

Tags are exact strings and the catalog carries far more of them than the obvious ones, so list them before guessing:

python3 -c "
import json,collections
e=json.load(open('$HUB_INDEX'))
c=collections.Counter(t for x in e for t in (x.get('tags') or []))
print(len(c),'distinct tags'); [print(f'{n:4d}  {t}') for t,n in c.most_common()]
"

Then try the tags that plausibly match the keyword. Rules:

• Zero on-topic matches: no page is possible. The build silently drops a page with an empty grid. Report "blocked on workflow supply, this needs the Hub workflow team" and stop. Never pad the grid with off-topic tags to fake supply.
• A page wants at least one App and at least one node graph in its grid (guide, "The Quality Bar"). The sweep above gives you both counts; they go in the PR body.
• Workflows exist but none of the on-topic ones is an App: this is a requester decision, not yours. Ask explicitly: ship now with an honestly empty "Comfy Apps" tab (noting "no on-topic App exists yet" in the PR body), or hold the page until the Hub workflow team publishes one. Wait for the answer.

Step 4: App verification (human eyes required)

If the page should have a "Try on Cloud" button opening an App (appShareId), or a pin marked isApp: true, ask the requester (or the person they delegate) to open https://cloud.comfy.org/?share=<shareId> and confirm: it opens in App Mode (a form, not the node canvas) and its sample assets load. Only after that confirmation may you set those fields. API data alone (linearMode) says it is an app, not that it works.

If no verified app exists, omit appShareId entirely and note it in the PR. An empty "Comfy Apps" tab is honest; a broken button is not.

Step 5: Apply the conventions and show them

Derive and present, without asking (they are site-wide conventions, per the guide):

• slug: kebab-case, usually ai-<use case> (e.g. ai-logo-generator)
• title: <Use Case> | Comfy Workflows
• h1: <Use Case> Workflows

Show the requester: "Your page will be /workflows/use-cases/ai-logo-generator/, titled 'AI Logo Generator | Comfy Workflows'." They only need to speak up if the use-case name is wrong. Propose ~6 secondary keywords from the cluster and get a yes.

Step 6: Content

Sources, in order of preference:

1. A Figma design for the page: extract the copy from it (if you cannot access Figma, ask the requester to paste the text or drop screenshots and read the text from those). The design's words win. Fill only the gaps, usually metaDescription and extra FAQs, and label which parts you drafted. If the design shows a section the page template does not render, stop and say that part needs an engineer; do not improvise template changes.
2. Copy the requester provides: format it into the fields.
3. Nothing provided: draft everything yourself.

Before drafting, read two or three existing files in site/src/content/landing/use-cases/ to match structure and tone. Then write fresh copy for this keyword; never reuse sentences from other pages. Field targets are in the guide's content table (metaDescription 150-160 chars containing the primary keyword; howToUse 4-8 verb-first steps; 6-8 FAQs answering real search questions and claiming nothing the grid cannot do).

Review checkpoint (mandatory): present the draft to the requester section by section in plain English, not JSON: headline, subheading, description, each FAQ, the workflows the grid will show, and what the button opens. Apply their edits verbatim. Do not write any file until they approve the content.