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.
| Mode | Main question | Main evidence shape |
|---|---|---|
| Versus comparison | How do named entities differ? | One research report per entity plus head-to-head evidence |
| Competitor intelligence | Which peers matter around a named entity? | Discovered peers plus one report per entity |
| Hiring signals | What areas may a company be investing in? | Current public roles grouped into focus themes |
| Jobs discovery | What 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
| Trigger | Consequence | Guard |
|---|---|---|
| A competitor run uses names without per-entity context | Peer evidence is thin or aimed at the wrong entity | Build a per-entity plan with resolved communities, accounts, code projects, and context |
| A peer inherits the primary entity's review or product targeting | One entity's evidence is presented as another entity's evidence | Keep peer fields in the peer plan and keep primary-only fields on the outer run |
| Competitor discovery has no usable web or company-index results | The system cannot form a trustworthy peer set | Use an explicit peer list or stop the comparison instead of guessing |
| Jobs retrieval falls to a sitemap or general web search | Role detail or freshness may be incomplete | Surface the tier, titles-only state, and coverage note in the evidence |
| A sitemap has role URLs but cannot provide titles | The board count survives but role-level hiring themes cannot be formed | Keep the count and missing-title state separate from titled role evidence |
| A jobs board is only partly read before its time budget ends | Hiring themes can reflect an incomplete board | Keep the partial-coverage note and avoid treating selected roles as the full board |
| Sitemap last-modified values are treated as posting dates | The report claims false recency or a false count of new roles | Treat sitemap rows as undated unless a supported source provides a posting date |
| Story search stops after a timeout or rate limit | Requested story terms have uneven coverage | Record the partial search state and continue with the normal board read |
| Hiring evidence is judged by raw role count alone | A large routine team can hide a small new capability | Check named teams, strategic single-role flags, and company-size context |
| A hiring brief turns a role into a product promise | The output claims a roadmap that the evidence does not prove | Use focus or priority language and link the source roles |
| Too many entity sub-runs fail | The merged comparison has no valid peer basis | Require the primary report and at least one peer before rendering |
Key files
| File | Why to read it |
|---|---|
| skills/…/SKILL.md | Defines the user-facing protocols for versus, competitor, and hiring modes. |
| skills/…/planner.py | Shows how comparison intent becomes entity-focused retrieval work. |
| skills/…/competitors.py | Explains company-index and web peer discovery at a high level. |
| skills/…/fanout.py | Shows how independent entity reports survive partial failure and merge in order. |
| skills/…/jobs.py | Defines careers-page-first jobs retrieval, story-directed board search, coverage, and time budgets. |
| skills/…/sitemap.py | Defines the bounded sitemap fallback and the limits of title and date evidence. |
| skills/…/jobs_story.py | Defines the short story terms that guide board search. |
| skills/…/jobs_digest.py | Shows how a large board becomes a bounded set of role evidence. |
| skills/…/jobs_teams.py | Shows how repeated title phrases expose named teams and team leads. |
| skills/…/hiring_signals.py | Defines hiring themes, strategic roles, and confidence treatment. |
| skills/…/pipeline.py | Connects source retrieval, hiring analysis, and report artifacts. |
| skills/…/render.py | Shows how comparison tables and hiring sections enter the final brief. |
| skills/…/schema.py | Defines the shared plan, source item, candidate, and cluster concepts. |