Introducing a new way to review your PRs.

Read the announcement

mvanhorn / last30days-skill

AI agent skill that researches any topic across Reddit, X, YouTube, HN, Polymarket, and the web - then synthesizes a grounded summary

View on GitHub

21 documents · Updated Nov 20, 2026

docs / competitor-and-hiring-research-modes

Competitor and hiring research modes

Competitor and hiring modes adapt the general research pipeline for questions about market alternatives and company direction. Competitor modes build a balanced view across several entities. Hiring mode turns current public job data into cautious signals about areas of focus. Both modes use the same source retrieval, evidence ranking, and briefing stages as the general pipeline, but they change how the plan is made and how evidence is grouped.

Specialized research scope

The general pipeline answers one topic with a plan, source searches, normalized evidence, ranking, and a brief. These modes add an explicit comparison or a jobs signal layer rather than creating a separate research system. See research skill execution for the wider run lifecycle.

Mode boundaries

The system treats a versus question and a competitor request as related but distinct entry points. A versus question supplies the entities. A competitor request discovers peers first, then follows the same versus path. Hiring mode does not compare product claims; it reads current roles as evidence of possible company priorities.

ModeMain questionMain evidence shape
Versus comparisonHow do named entities differ?One research report per entity plus head-to-head evidence
Competitor intelligenceWhich peers matter around a named entity?Discovered peers plus one report per entity
Hiring signalsWhat areas may a company be investing in?Current public roles grouped into focus themes
Jobs discoveryWhat public roles are open?A current board snapshot that can feed hiring analysis

References: skills/…/SKILL.md• L1089-1099 skills/…/SKILL.md• L1161-1187 skills/…/planner.py• L97-115

Competitor intelligence

Competitor intelligence expands a primary topic into a small market set. It aims to compare the primary entity with peers that appear in current competitor, alternative, and versus discussions instead of relying on a fixed peer list.

Peer discovery

The skills/…/competitors.py discovery flow uses a company index when the topic is resolved as a company and an Exa key is available. It then fills any remaining peer slots with recent web results from competitor, alternative, and versus searches. Candidate names are cleaned, deduplicated, and ordered by source recurrence or source order rather than accepted as raw search-result text.

The preferred path supplies a per-entity plan after discovery. A name-only list is an escape hatch. It lets the run continue, but it gives peer reports less precise targeting than the main report. Person and artist topics skip company-index discovery and use keyword search only.

References: skills/…/competitors.py• L22-29 skills/…/competitors.py• L169-215 skills/…/competitors.py• L232-319

Entity planning

The planner treats a versus topic as a set of entities plus a shared comparison intent. It creates a primary query and adds an entity-focused query for each named entity at normal depth. Each entity should also have its own resolved context, such as relevant communities, public accounts, code projects, and current positioning. This keeps a peer's evidence from becoming a weak keyword search beside a well-targeted primary report.

The entity plan carries the targeting for peers. The main entity keeps its targeting on the normal run options. This split matters for fields such as review domains because a peer must not inherit the main entity's identity.

References: skills/…/planner.py• L678-689 skills/…/SKILL.md• L1091-1093 skills/…/SKILL.md• L1149-1155

Parallel entity fan-out

The comparison flow runs the primary entity and each peer as full research runs. The fan-out returns separate reports and preserves the requested entity order. A failed peer can be dropped without losing the comparison when the primary report and at least one peer survive.

This diagram shows how a competitor request becomes several entity reports and then one comparison brief.

flowchart LR
    A[Primary topic] --> B[Discover or accept peers]
    B --> C[Resolve context for each entity]
    C --> D[Build entity-specific plans]
    D --> E1[Primary research run]
    D --> E2[Peer research run]
    D --> E3[Peer research run]
    E1 --> F[Normalize and rank each report]
    E2 --> F
    E3 --> F
    F --> G[Merge into comparison briefing]

The fan-out is still the general pipeline at the entity level. Its special role is to keep each report independent until the final merge. See research planning and querying for the normal plan contract and source retrieval and connectors for source behavior.

References: skills/…/fanout.py• L1-12 skills/…/fanout.py• L30-88 skills/…/last30days.py• L3666-3765

Comparison evidence

Each entity report passes through the normal evidence path. Source records become common evidence items, then candidates and ranked clusters. The comparison layer keeps those groups attached to their entity so a strong result for one product does not look like evidence for another.

The comparison also adds direct rivalry searches. Per-entity evidence explains what each entity is doing. Head-to-head searches explain how people frame the entities against each other. Current first-party positioning can describe the “What it is” view when the run fetched that positioning, but the brief must not fill missing positioning from memory.

References: skills/…/schema.py• L45-72 skills/…/schema.py• L75-139 skills/…/SKILL.md• L1151-1159

Comparison briefing

The briefing stage merges the surviving reports into one output. It exposes the entity set and resolved context, keeps evidence sections separate by entity, and provides a head-to-head table for short comparisons. The final synthesis then draws a choice or fit statement from the evidence rather than treating the table as a raw data dump.

The renderer uses a shared scaffold for the comparison axes. An axis that does not fit the topic receives no invented claim. The result remains useful for products, companies, people, or other named entities without forcing every topic into the same feature set. See briefings and rendered output for the wider output contract.

References: skills/…/render.py• L1313-1365 skills/…/render.py• L1368-1464 skills/…/render.py• L1467-1515

Hiring signals and jobs discovery

Jobs discovery supplies the raw view of a company's open roles. Hiring signals turns that view into a smaller set of evidence-backed themes. The distinction protects the brief from treating every job title as a strategy statement.

Jobs-first retrieval

The skills/…/jobs.py jobs flow starts with the company's known official site or a careers page found through controlled discovery. It reads a linked public board through its supported provider when possible. If that path fails, it can use a job sitemap or structured JobPosting data before falling back to general web search. The retrieval artifact records coverage, ownership, and the tier that produced the roles.

The sitemap tier can count role URLs even when role pages are blocked. It may get titles from URL slugs or from a bounded sample of role pages. Sitemap last-modified values do not establish posting dates, so this path cannot support a count of roles new in the time window.

The jobs lane uses one time budget for the board and its role details. In a comparison, that budget is shared across entities so one slow board cannot consume the whole run. Partial reads remain visible as partial coverage rather than appearing to be a complete company view. A direct board is a current company view. Search results can be incomplete or stale and must be described as such.

References: skills/…/jobs.py• L1-21 skills/…/jobs.py• L544-592 skills/…/jobs.py• L771-885 skills/…/jobs.py• L1483-1513 skills/…/sitemap.py• L107-173 skills/…/sitemap.py• L213-258

Story-directed retrieval

Jobs retrieval can carry a few story terms from the run's research plan. The lane searches a board for those terms before or during its normal board read when the provider supports that action. It marks matching roles and keeps those matches available for the digest, while recording when a search stopped early or did not run. This lets a jobs lane support the report's question without replacing the full board view with a keyword result.

When the plan does not provide terms, the system derives short phrases from its subqueries and removes company names, comparison entities, and generic words. It caps the terms so the directed search remains a bounded aid to the normal retrieval path. In a comparison, the per-company call allowance is reduced so all entities retain a fair share of the lane.

References: skills/…/jobs.py• L353-381 skills/…/jobs.py• L384-497 skills/…/jobs_story.py• L1-22 skills/…/jobs_story.py• L75-134

Role normalization

The normalizer turns each job into a common source item. The item keeps the role title, description, team, location, board provider, and source link. A board is treated as a company-level open-role view, so the pipeline keeps its reported role count and coverage notes instead of applying the small per-source limit used by many discussion sources.

Hiring analysis groups roles into broad themes such as enterprise readiness, go-to-market, AI and machine learning, infrastructure, product expansion, and data. It gives more weight to a match in the title or department than to repeated boilerplate in the description. It also flags founding, leadership, specialized, and new-location roles that may carry more meaning than their count suggests. The final judgment needs company context because the role title alone cannot prove that a capability is new.

References: skills/…/normalize.py• L353-395 skills/…/hiring_signals.py• L15-41 skills/…/hiring_signals.py• L218-249 skills/…/hiring_signals.py• L375-412

Role digest and named teams

The jobs digest gives the briefing a bounded view of a large board. It merges postings that represent one role across locations and keeps text that is distinctive to the role instead of repeating company boilerplate. Selection favors roles found by story terms, named teams, rare board-level traits, and strategic title markers.

Named-team analysis finds repeated team phrases in titles and also surfaces a lead or founding role for a small team that appears only a few times. This adds a way to detect an emerging team even when no external story names it. The digest remains evidence selection; it does not decide what the team means for the company.

References: skills/…/jobs_digest.py• L1-7 skills/…/jobs_digest.py• L103-196 skills/…/jobs_digest.py• L339-376 skills/…/jobs_teams.py• L1-14 skills/…/jobs_teams.py• L72-85

Hiring signal thresholds

The analyzer weighs role count with team spread, seniority, strategic title markers, and a rough company-size tier. This avoids reading five routine engineering roles at a large company in the same way as five roles at a small startup. Explicit hiring mode can show available signals even when the evidence is thin. Standard company research keeps only signals that clear the normal confidence bar.

The safe interpretation is a focus signal. “The company appears to be increasing focus on enterprise readiness” is supported language. “The company will ship single sign-on next quarter” is not supported by job postings alone.

References: skills/…/hiring_signals.py• L77-120 skills/…/hiring_signals.py• L123-156 skills/…/hiring_signals.py• L295-358

Hiring briefing integration

The pipeline stores the hiring analysis beside the report evidence. The renderer adds a Hiring Signals section when the mode is explicit or when a standard run has a strong enough signal. It can show the mode, company-size tier, confidence, themes, representative roles, and strategic single-role candidates. The jobs digest and named-team view give synthesis enough role-level evidence to weigh a new bet against raw hiring volume.

This diagram shows the jobs path from a public board to a cautious briefing claim.

flowchart LR
    A[Company topic] --> B[Find careers page]
    B --> C[Read public job board]
    C --> D[Normalize roles]
    D --> E[Search story terms and find named teams]
    E --> F[Build bounded role digest]
    F --> G[Group themes and flag strategic roles]
    G --> H[Apply size-aware confidence]
    H --> I[Hiring Signals section]
    I --> J[Briefed focus signal]

If no clear signal survives, an explicit run reports that the evidence is missing or too diffuse. A standard run omits the hiring section instead. See research quality and ranking for the broader evidence rules and watchlists, library, and store for ways to retain results over time.

References: skills/…/pipeline.py• L2544-2550 skills/…/render.py• L2209-2288 skills/…/last30days.py• L3807-3810

Change checklist

When these files or sections are changed, remember to consider these:

  • Changes to comparison entity parsing must stay aligned with peer routing and the head-to-head table columns.
  • Changes to peer targeting must preserve the separation between the primary entity's options and each peer's plan entry.
  • Changes to company-index or web discovery must keep candidate cleanup, company detection, and peer ordering consistent.
  • Changes to jobs retrieval tiers must keep ownership, coverage, and retrieval tier visible to hiring analysis so confidence does not look the same for board data and fallback data.
  • Changes to sitemap parsing or title recovery must preserve the difference between a role count, titled role evidence, and a title-only board with no posting-date evidence.
  • Changes to story-term derivation or board search must preserve the distinction between a partial search and no matching roles.
  • Changes to normalized job fields must update theme grouping, named-team discovery, digest selection, and strategic-role detection because they depend on the same role record.
  • Changes to digest selection must preserve the role-count and coverage meaning of the full board; selected roles are examples, not the board total.
  • Changes to hiring thresholds must preserve the difference between explicit hiring reports and optional hiring sections in standard reports.
  • Changes to comparison fan-out failure handling must keep the rule that a comparison needs the primary report plus at least one surviving peer.

Important failure modes

TriggerConsequenceGuard
A competitor run uses names without per-entity contextPeer evidence is thin or aimed at the wrong entityBuild a per-entity plan with resolved communities, accounts, code projects, and context
A peer inherits the primary entity's review or product targetingOne entity's evidence is presented as another entity's evidenceKeep peer fields in the peer plan and keep primary-only fields on the outer run
Competitor discovery has no usable web or company-index resultsThe system cannot form a trustworthy peer setUse an explicit peer list or stop the comparison instead of guessing
Jobs retrieval falls to a sitemap or general web searchRole detail or freshness may be incompleteSurface the tier, titles-only state, and coverage note in the evidence
A sitemap has role URLs but cannot provide titlesThe board count survives but role-level hiring themes cannot be formedKeep the count and missing-title state separate from titled role evidence
A jobs board is only partly read before its time budget endsHiring themes can reflect an incomplete boardKeep the partial-coverage note and avoid treating selected roles as the full board
Sitemap last-modified values are treated as posting datesThe report claims false recency or a false count of new rolesTreat sitemap rows as undated unless a supported source provides a posting date
Story search stops after a timeout or rate limitRequested story terms have uneven coverageRecord the partial search state and continue with the normal board read
Hiring evidence is judged by raw role count aloneA large routine team can hide a small new capabilityCheck named teams, strategic single-role flags, and company-size context
A hiring brief turns a role into a product promiseThe output claims a roadmap that the evidence does not proveUse focus or priority language and link the source roles
Too many entity sub-runs failThe merged comparison has no valid peer basisRequire the primary report and at least one peer before rendering

Key files

FileWhy to read it
skills/…/SKILL.mdDefines the user-facing protocols for versus, competitor, and hiring modes.
skills/…/planner.pyShows how comparison intent becomes entity-focused retrieval work.
skills/…/competitors.pyExplains company-index and web peer discovery at a high level.
skills/…/fanout.pyShows how independent entity reports survive partial failure and merge in order.
skills/…/jobs.pyDefines careers-page-first jobs retrieval, story-directed board search, coverage, and time budgets.
skills/…/sitemap.pyDefines the bounded sitemap fallback and the limits of title and date evidence.
skills/…/jobs_story.pyDefines the short story terms that guide board search.
skills/…/jobs_digest.pyShows how a large board becomes a bounded set of role evidence.
skills/…/jobs_teams.pyShows how repeated title phrases expose named teams and team leads.
skills/…/hiring_signals.pyDefines hiring themes, strategic roles, and confidence treatment.
skills/…/pipeline.pyConnects source retrieval, hiring analysis, and report artifacts.
skills/…/render.pyShows how comparison tables and hiring sections enter the final brief.
skills/…/schema.pyDefines the shared plan, source item, candidate, and cluster concepts.