Competitors Analysis

Competitors Analysis

Build competitor intelligence that can be shared, re-run, and audited later. This skill has two layers:

1. Repository evidence: clone or update the competitor code under the durable competitors workspace, then cite facts from actual files and commits.
2. Landscape synthesis: summarize positioning, pricing, strengths, weaknesses, gaps, and opportunities, but only after separating sourced facts from judgment.

This skill intentionally subsumes lightweight "competitor scan" workflows. A scan is useful for the landscape table, but it is not enough for technical conclusions.

Stop Gate — required input (read this first)

This skill runs as context: fork and cannot ask the user anything. The "ask if missing" pattern below therefore does not apply to you. Enforce this hard gate as your very first action:

If the caller did not pass an explicit product/market target for THIS invocation, STOP immediately. Report back: "competitors-analysis needs an explicit product-name or market; none was provided, and as a background fork I cannot ask — aborting rather than inventing a target." Then exit.

Do not:

• invent or infer a target — a plausible task you generated yourself is still fabricated, not the user's;
• run ls on $COMPETITORS_BASE to pick an existing product directory as your target;
• fall through to Discover mode to fill the gap.

A target counts as "provided" only if it came from the caller's request/arguments this invocation — not from a directory name on disk, not from your own reasoning.

Entry Router

If the user's request is missing the product/market or target customer segment, ask for that context before synthesizing positioning or opportunity claims (in context: fork you cannot ask — the Stop Gate above already handled the missing-target case; if you reached here, a target was provided). Known competitors are optional; if absent, use Discover mode.

Use the user's wording to choose the path:

Durable Source Layout

Use a durable workspace, not /tmp. The default base is:

COMPETITORS_BASE="${COMPETITORS_BASE:-$HOME/workspace/competitors}"

Directory convention:

$COMPETITORS_BASE/
└── {product-slug}/
    ├── {owner-repo}/
    └── ...

Use owner-repo for GitHub repositories so forks and similarly named projects do not collide. If the caller named a product directory this invocation and it already exists on disk, use it as the source of truth and do not re-clone elsewhere. Never adopt an existing product directory the caller did not name this invocation — that is exactly how a target-less fork silently picks up an unrelated project (2026-09-20 incident: a no-arg fork fabricated an "A2A market" task and ratified it by reusing the on-disk agent-communication dir for 1h23m).

Preflight

Before analysis, establish these facts from commands, not memory:

repo="$COMPETITORS_BASE/{product-slug}/{owner-repo}"
test -d "$repo/.git"
git -C "$repo" remote -v
git -C "$repo" fetch --all --prune
git -C "$repo" log -1 --format='%H%x09%cI%x09%s'

If the repository is missing, clone it first. Prefer SSH for GitHub when possible:

mkdir -p "$COMPETITORS_BASE/{product-slug}"
git clone --depth 1 <git-ssh-url> "$COMPETITORS_BASE/{product-slug}/{owner-repo}"

If SSH fails for a public repository, report the failure and retry with the repository's HTTPS URL only when that keeps the work moving.

Discovery Workflow

Use gh search repos for GitHub repository discovery. Search multiple query phrases; do not trust one keyword.

gh search repos "product keywords" \
  --limit 30 \
  --archived=false \
  --json fullName,url,description,stargazersCount,forksCount,openIssuesCount,language,pushedAt,updatedAt,defaultBranch

For each candidate, record:

Clone only candidates that are relevant to the user's product or analysis goal. For broad markets, first present a shortlist with evidence and then analyze the strongest set.

Repository Fact Gathering

Read files in this order and capture exact sources:

1. Project metadata: package.json, pyproject.toml, Cargo.toml, go.mod, or equivalent.
2. README and docs: positioning, screenshots, installation, pricing links.
3. Entry points: main, bin, scripts, src/, app/, packages/.
4. Core implementation: renderer, parser, storage, export, sync, auth, API, or domain-specific modules.
5. Tests and fixtures: they often reveal supported data structures and edge cases.
6. Releases/changelog: current direction and recent changes.

Use nl -ba <file> or an editor with line numbers before citing. Every technical claim about implementation needs file:line evidence.

Report Structure

For a single competitor, use references/profile_template.md.

For a landscape summary, use this structure:

# {Product} Competitor Landscape

## Source Register
| Competitor | Local path | Remote | Commit | Retrieved |
|---|---|---|---|---|

## Positioning
| Competitor | User segment | Primary promise | Source |
|---|---|---|---|

## Product And Technical Comparison
| Dimension | Competitor A | Source | Competitor B | Source | Our product | Source |
|---|---|---|---|---|---|---|

## Strengths
| Competitor | Strength | Evidence | Why it matters |
|---|---|---|---|

## Weaknesses And Gaps
| Competitor | Gap | Evidence | Opportunity |
|---|---|---|---|

## Opportunities
| Opportunity | Evidence base | Product implication | Confidence |
|---|---|---|---|

## Risks And Assumptions
| Item | What is known | What still needs verification | Next check |
|---|---|---|---|

Evidence Rules

Required

Forbidden

Do not write unsupported technical claims. Avoid these patterns unless they appear inside an explicit "bad example" block:

When evidence is unavailable, write 待验证 and state the exact next check that would verify it.

Output Quality Bar

Before finishing, run the checks in references/analysis_checklist.md:

• Local repository exists under $COMPETITORS_BASE/{product-slug}/.
• Remote URL and latest commit are recorded.
• Each technical claim has a file:line citation.