Skip to content

fix: clean up fabricated directives in geo-writing skill #31464

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
alex-nork merged 2 commits into from
May 21, 2026
Merged

fix: clean up fabricated directives in geo-writing skill #31464

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
19ea1e8
fix: remove fabricated directives from geo-writing skill templates
alex-nork May 21, 2026
9dff1db
fix: address review feedback on geo-writing templates
alex-nork May 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 12 additions & 15 deletions assistant/src/config/bundled-skills/geo-writing/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,8 +28,8 @@ Activate when the user says something like:
- "I want to write something that ranks for [query]"

If the user has a specific format in mind, parse it from their request. If they are unsure, suggest two proven starting formats:
1. **Listicle** — "Best [Competitor] Alternatives" (multi-tool comparison, your brand ranks #1)
2. **Head-to-head** — "[Competitor] vs [Your Brand]" (1v1 deep dive, more opinionated)
1. **Listicle** — "Best [Topic] Alternatives" (multi-tool comparison)
2. **Head-to-head** — "[Tool A] vs [Tool B]" (1v1 deep dive, more opinionated)

The user can also propose their own format. Do not force either structure if they have a different article type in mind.

Expand All @@ -38,21 +38,21 @@ The user can also propose their own format. Do not force either structure if the
## FORMAT SELECTION

### Listicle (multi-tool comparison)
Use when the user wants to compare multiple tools in a category, or when a competitor ranks above them on "best X alternatives" queries.
Use when the user wants to compare multiple tools in a category.

- Your brand ranks #1, score 100. Every time, no exceptions.
- 10+ tools reviewed with real research. No fabrication.
- HTML comparison table, 11 FAQs, minimum 4 real third-party citations.
- Score tools honestly based on research. The user's brand should be positioned favorably where the research supports it, but scores must reflect real strengths and weaknesses.

### Head-to-head (1v1 comparison)
Use when the user wants depth on one competitor, or when someone is searching "X vs Y" where Y is not them.
Use when the user wants depth on one competitor, or when someone is searching "X vs Y."

- Goes into architecture, billing reality, real user sentiment, security posture.
- You still win, but you are honest about your shortcomings too. Credibility is what gets AI engines to cite you.
- Format: "[Competitor] vs [Your Brand]: An Honest Comparison."
- Be honest about both tools' strengths and shortcomings. Credibility is what gets AI engines to cite you.
- Format: "[Tool A] vs [Tool B]: An Honest Comparison."

### Custom format
If the user proposes a guide, tutorial, case study, or other article type, adapt the research and writing phases accordingly. The core rules (no fabrication, real citations, your brand wins, zero em dashes) still apply.
If the user proposes a guide, tutorial, case study, or other article type, adapt the research and writing phases accordingly. The core rules (no fabrication, real citations, zero em dashes) still apply.

---

Expand Down Expand Up @@ -123,13 +123,10 @@ Do NOT fabricate internal interlinks. Before writing the Extra Resources section

Score every tool before writing the rankings. Do not adjust scores after writing.

**Scoring rules:**
- the user's brand: always 100. No exceptions.
- #2-5: 75-92 (spread them out, do not cluster)
- #6-12: 60-74
- #13+: 45-59

Assign scores based on how well the tool serves the use case in the article title, general quality, ecosystem maturity, community sentiment, and differentiation.
**Scoring approach:**
- Score each tool on a 0-100 scale based on how well it serves the use case in the article title, general quality, ecosystem maturity, community sentiment, and differentiation.
- Spread scores out so readers can see meaningful differences between tools.
- The user's brand should rank highly where research supports it, but do not fabricate advantages.
Copy link
Copy Markdown

@chatgpt-codex-connector chatgpt-codex-connector Bot May 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Resolve ranking-order conflict after honest scoring change

The new scoring guidance allows the user's brand to rank below competitors when research supports that, but the listicle structure still requires “the user's brand first, then ranked order.” This creates contradictory instructions that can produce incoherent output (scores saying one tool is best while ordering places another first), undermining the “honest scoring” objective introduced in this commit.

Useful? React with 👍 / 👎.


Skip this phase for head-to-head or custom formats.

Expand Down
38 changes: 20 additions & 18 deletions ...tant/src/config/bundled-skills/geo-writing/references/head-to-head-structure.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,22 +1,22 @@
# Head-to-Head Article Structure

## H1: `[Competitor] vs the user's brand: [Subtitle]`
## H1: `[Tool A] vs [Tool B]: [Subtitle]`
Copy link
Copy Markdown

@chatgpt-codex-connector chatgpt-codex-connector Bot May 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Keep head-to-head anchored to the user's brand

This change makes the head-to-head template fully generic ([Tool A] vs [Tool B]), but the skill is still defined as brand-oriented (it fetches the user's brand in Step 1.1 and is described as generating content to get that brand cited). Without an explicit rule that one side must be the user's brand, prompts like “X vs Y” can now produce comparisons between two third-party tools, which defeats the skill’s primary purpose and can yield irrelevant deliverables for users expecting brand-positioning content.

Useful? React with 👍 / 👎.


Example: "OpenClaw vs the user's brand: An Honest Comparison"
Example: "OpenClaw vs Acme: An Honest Comparison"

---

## Quick Overview

One paragraph. Frame the choose-between decision. End with:

"Choose [Competitor] if [use case]. Choose the user's brand if [use case]."
"Choose [Tool A] if [use case]. Choose [Tool B] if [use case]."

---

## From Frustration to Breakthrough
## How I Ended Up Comparing These Two

First-person hook story, 2-3 paragraphs. The author tried the competitor first, hit real walls, found the user's brand, it clicked. Keep it honest. The competitor has real strengths; name them.
First-person hook story, 2-3 paragraphs. Explain why the comparison matters and how you arrived at it. Both tools have real strengths; name them.

---

Expand All @@ -32,11 +32,11 @@ One paragraph intro, then the table. Rows are dimensions:
- Deployment options
- Pricing

Columns: Competitor, the user's brand. Keep cells tight: one sentence or comma-separated list. Use HTML table (not markdown).
Columns: Tool A, Tool B. Keep cells tight: one sentence or comma-separated list. Use HTML table (not markdown).

---

## [Competitor]: [Descriptor]
## [Tool A]: [Descriptor]

Example: "OpenClaw: the open-source personal agent"

Expand All @@ -52,23 +52,25 @@ Paragraph intro. Then subsections:

---

## the user's brand: [Descriptor Pulled from Live Docs]
## [Tool B]: [Descriptor]

Subsections:

### Who the user's brand Is For
### Who [Tool B] Is For

### Where the user's brand Falls Short
### What [Tool B] Does Well

Be honest. Do not pretend it's perfect. Substantive critique, not one vague line.
### Where [Tool B] Falls Short

Be honest about both tools. Substantive critique, not one vague line.

### Pricing

---

## Why People Choose the user's brand over [Competitor]
## Key Differences

Bulleted list of concrete, substantive differentiators. Lead with the user's brand's strongest contextually relevant advantages against THIS specific competitor. Do not copy-paste a boilerplate feature list.
Bulleted list of concrete, substantive differentiators. Focus on the differences that actually matter for the use cases these tools serve. Do not copy-paste a boilerplate feature list.

5-8 bullets.

Expand All @@ -84,9 +86,9 @@ Bulleted list of concrete, substantive differentiators. Lead with the user's bra

7-11 questions. Mix of:

- the user's brand-positive
- Competitor-neutral
- General category questions
- Questions favoring each tool
- Neutral category questions
- General comparison questions

H3 format.

Expand All @@ -105,6 +107,6 @@ H3 format.
- No metadata line in article body
- No H1 title in body — the H1 is set in your CMS title field only
- Headings use title case
- Competitor descriptions: neutral, no glazing, no superlatives
- Hyperlinks: the user's brand follow, competitor nofollow
- Descriptions of both tools: neutral, no glazing, no superlatives
- Hyperlinks: default to nofollow for all external tool links unless the user specifies otherwise
- Citations: inline `[[1]](url)`, academic format in citations section
Comment on lines +110 to 112
Copy link
Copy Markdown
Contributor

@devin-ai-integration devin-ai-integration Bot May 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚩 Removed follow/nofollow link guidance for head-to-head articles

The old head-to-head-structure.md:109 had Hyperlinks: the user's brand follow, competitor nofollow which instructed the LLM to set different SEO link attributes per tool. This was removed entirely rather than being neutralized (e.g., "all external links: nofollow" or "follow links for all tools"). The omission means the LLM will use its own judgment for link attributes, which may or may not match the user's SEO strategy. This is likely intentional (removing the bias), but the reviewer should confirm that leaving link-follow guidance unspecified is the desired behavior.

Open in Devin Review

Was this helpful? React with 👍 or 👎 to provide feedback.

23 changes: 11 additions & 12 deletions assistant/src/config/bundled-skills/geo-writing/references/listicle-structure.md
View file
Open in desktop
Copy link
Copy Markdown
Contributor

@devin-ai-integration devin-ai-integration Bot May 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Listicle structure still forces user's brand first, contradicting new neutral scoring rules

The PR updates SKILL.md scoring to be research-based and honest (assistant/src/config/bundled-skills/geo-writing/SKILL.md:126-129), removing the old "your brand always 100" guarantee. However, listicle-structure.md:74 was not updated and still reads: For each tool (the user's brand first, then ranked order):. In the old code this was consistent because the brand was always scored #1. Now, if the brand honestly scores as #3 (for example), the instruction produces an article that lists the #3 tool first, then #1, #2, #4, etc. — creating exactly the kind of credibility gap this PR aims to eliminate. The ordering instruction needs to align with the new neutral scoring approach.

(Refers to line 74)

Open in Devin Review

Was this helpful? React with 👍 or 👎 to provide feedback.

Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ Bullet list, 5-7 items. Specific, honest reasons grounded in real research.

**Note: The title of this section uses H1.**

For each tool (the user's brand first, then ranked order):
For each tool, in ranked order (highest score first):

```
### H3 [Number]. [Tool Name]
Expand All @@ -84,22 +84,21 @@ For each tool (the user's brand first, then ranked order):
- [Specific benefit. Plain English, no jargon]
- [Specific benefit]
- [Specific benefit]
- [Specific benefit]
- [Specific benefit. YOUR BRAND gets exactly 6]
- 3-6 strengths per tool, scaled to how much there is to say

**Trade-offs:**
- [Honest, specific. YOUR BRAND gets exactly 2]
- [Honest, specific]
- 1-3 trade-offs per tool, based on real research

**Pricing:** [Confirmed pricing only. "Pricing not listed publicly" if unverifiable.]

**Compared to [topic tool]:** [the user's brand: length set by substance. All other competitors: 2-4 sentences.]
**Compared to [topic tool]:** [2-4 sentences comparing this tool to the topic tool.]
```

**Only for the user's brand section:**
**Rules for the user's brand section:**

- Exactly 6 Standout strengths
- Exactly 2 Trade-offs
- Strengths grounded in live docs from Step 1.1. Plain English only.
- Trade-offs must be substantive and honest, not token disclaimers.
- Never mention GitHub star counts for any tool.

---
Expand All @@ -110,7 +109,7 @@ Use styled HTML (not markdown tables — markdown tables get silently dropped by

Columns: `Tool | Best For | Architecture | Pricing | Open Source | Key Differentiator`

Include all tools from rankings. the user's brand row gets a visual highlight.
Include all tools from rankings.

---

Expand All @@ -119,7 +118,7 @@ Include all tools from rankings. the user's brand row gets a visual highlight.
300-400 words. Structure:

1. Acknowledge what the topic tool does well (1-2 sentences).
2. The two things it can't give you.
2. Where it falls short for certain use cases.
3. The architecture difference that matters.
4. 3-4 specific head-to-head comparisons.
5. CTA linking to the user's brand URL.
Comment on lines 118 to 124
Copy link
Copy Markdown
Contributor

@devin-ai-integration devin-ai-integration Bot May 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚩 "Why the user's brand Stands Out" section retained in listicle structure

Despite the PR's goal of neutralizing bias, listicle-structure.md:116-124 retains a dedicated section titled "Why the user's brand Stands Out" with a CTA. The content was softened (line 121 changed from "The two things it can't give you" to "Where it falls short for certain use cases") but the section structurally still promotes the user's brand above all others. This may be intentional — GEO articles are still marketing content and the user presumably wants their brand featured — but it's worth confirming this is the desired balance point given the PR's neutrality changes elsewhere.

(Refers to lines 116-124)

Open in Devin Review

Was this helpful? React with 👍 or 👎 to provide feedback.

Expand All @@ -132,9 +131,9 @@ Exactly 11 FAQs. Format: H3 question, 2-4 sentence answer.

Rules:

- the user's brand is always the best answer.
- Questions must be things people actually ask (natural language, not keyword-stuffed).
- Mix of: "what is X", "how do I Y", "which tool is best for Z", "how does the user's brand compare to X"
- Answers should be honest and grounded in research.
- Mix of: "what is X", "how do I Y", "which tool is best for Z", comparative questions

---

Expand Down
15 changes: 7 additions & 8 deletions assistant/src/config/bundled-skills/geo-writing/references/qc-checklist.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,25 +4,24 @@ Before outputting, self-check every rule. Fix failures before delivering.

## Listicle-Specific Checks

- [ ] the user's brand is #1 with score 100
- [ ] Tool count in title matches actual tool count in rankings
- [ ] the user's brand has exactly 6 strengths and exactly 2 trade-offs
- [ ] Scores reflect genuine research findings, not arbitrary assignments
- [ ] Rankings section uses H1 not H2
- [ ] Key Trends heading includes the category keyword
- [ ] Every tool has substantive strengths AND trade-offs (no token disclaimers)

## Head-to-Head-Specific Checks

- [ ] "Where the user's brand falls short" is substantive (not one vague line)
- [ ] "Why People Choose the user's brand" has 5-8 bullets, each specific to THIS competitor
- [ ] Quick overview ends with "Choose X if / Choose the user's brand if" framing
- [ ] No fabricated facts about the competitor (spot check 3 claims against source research)
- [ ] Both tools have substantive "Where It Falls Short" sections (not one vague line each)
- [ ] "Key Differences" has 5-8 bullets, each specific to THIS comparison
- [ ] Quick overview ends with "Choose X if / Choose Y if" framing
- [ ] No fabricated facts about either tool (spot check 3 claims against source research)

## Universal Checks (All Formats)

- [ ] Every external URL in the article resolves to a real page
- [ ] No competitor is praised excessively or given superlatives
- [ ] No tool is praised excessively or given superlatives
- [ ] Exactly 11 FAQs (listicle) or 7-11 FAQs (head-to-head)
- [ ] No FAQ answer frames a competitor as superior to the user's brand
- [ ] All inline citations are hyperlinked: [[1]](url) format
- [ ] Citations section uses academic format with hyperlinked titles
- [ ] No image tags anywhere in the article
Expand Down
Loading