English | 简体中文

Askovo

Start from a business question, collect data, verify judgments, and deliver traceable research outcomes.

Askovo is built for product managers, user researchers, and business analysts. You bring the business goal, the context, and the permitted data sources; your agent plans the research actions, and Askovo executes the authorized collection, descriptive analysis, and evidence audits — producing research reports, MRD, PRD, or BRD that help the team decide what to do next and what still needs validation.

CLI, Skill, and MCP surfaces are live today. The host agent can author the action list, or askovo loop derives rounds from audit gaps inside an authorized envelope; the executor runs only what was authorized. Source gaps and human semantic review are kept explicit, never hidden. See capability status and trade-offs (Chinese).

scene → user → pain → need → feature → product → business

Data collection, descriptive analysis, interviews, experiments, evidence grading, and platform connectors are supporting steps only: they validate a node or an inference edge — they never substitute for the product and business reasoning itself.

Every line an AI research tool produces sounds equally confident — the evidenced and the invented look identical, and whoever signs off cannot tell which sentence to trust. Askovo grades every conclusion with an evidence level (E0–E5); when a conclusion outruns its evidence, askovo audit says so outright, and its exit code 1 can gate CI.

Website · Quickstart · Product & business reasoning chain · Role methodology · Platforms & connectors

Proof it works in 30 seconds

pipx install git+https://github.com/roy-tong/askovo.git
askovo do "home security camera false alerts at night, want to validate the prototype" --domain hardware --dry-run
askovo demo

No pipx? Use a virtualenv instead (verified from a clean venv on 2026-11-02, ~85s including download):

python3 -m venv .venv && .venv/bin/pip install "git+https://github.com/roy-tong/askovo.git"
.venv/bin/askovo demo

You can also route directly: askovo "SaaS subscription churn is dropping, want to know why users don't renew" --dry-run. --dry-run only routes and writes nothing; demo runs the built-in synthetic sample. Router keyword tables are Chinese-first — English queries work, and --domain pins the product type whenever English keywords don't match.

Language note (2026-11-02): CLI output is Chinese today; docs/ are Chinese too. The command surface, JSON output and audit exit codes are language-independent, so it is usable from an English workflow, but the rendered text will not be English. English localisation is not scheduled yet. Verified from a clean venv install on 2026-11-02: install ~85s, askovo demo exits 0.

Expected key results: status: pass, supported: 1, overclaims: 0. This only proves that the synthetic sample is self-consistent in structure, chain, and evidence references. It proves nothing about real demand, product quality, market size, or release readiness.

From research question to decision result: what a full delivery looks like

Feed in a decision question, get back a Decision Package — every judgment traceable along the seven-node chain to its evidence and counter-evidence. Using the built-in synthetic sample (examples/sample-study):

Research question: for remote pet owners, is it worth running a two-week phone-based check-in pilot for "pet watch while away from home"?

Once the chain is complete (all seven nodes validated, 2 counter-evidence items on record), one command produces the decision package:

askovo chain examples/sample-study
askovo deliver examples/sample-study --kind decision   # → 06-report/decision-package.md

The decision package gives the decision maker five views:

Sample decision memo (excerpt, from the synthetic sample): prioritization method — "test privacy, acceptance and retained use before any scale decision"; rationale — "the smallest test that can reverse the concept; no market-size ranking is claimed"; confidence bounds — counter-evidence R05/R07, gaps include "Privacy controls are not tested in real homes"; three states — delivery unplanned / outcome observing / causality not-claimed. decided is only a record of choice, not release or commercial proof — the three states are independent and must not be inferred from one another.

MRD/PRD/BRD are not three separate sets of conclusions — they are market/requirements/business projections of the same chain; the decision package is their decision-side summary view.

The three recurring tasks all run the same chain and differ only in what they deliver: discover (research question → Opportunity Map), validate (review a hypothesis → Validation Backlog), decide (compare candidates → Decision Memo).

One chain, many roles, five domains

A small team can wear several hats, but the workflows and outputs must not be conflated:

All five domains share one chain schema — no per-domain forking. Domain packs only change methods, evidence forms, risk gates, and acceptance focus. Current first focus: AI software, developer tools, and smart hardware (the five-domain methodology stays compatible):

How it works

1. Build the product and business reasoning first; decide what to research second

askovo do "SaaS subscription churn is dropping, want to know why users don't renew"
askovo chain ./askovo-software-postlaunch

do detects domain, lifecycle stage, intent, and risks, then creates the chain canvas. chain renders the same machine truth:

04-findings/product-reasoning.json   seven nodes, inferences, assumptions, counter-evidence, decision states
06-report/product-reasoning.md       human-readable projection

Every node must carry:

• statement: the current judgment;
• rationale: why the previous node licenses this one;
• assumptions: what must also hold for the inference to stand;
• evidence_ids: which registered evidence supports it;
• status: hypothesis / needs-validation / validated / rejected / deprioritized.

Feature nodes also record alternatives and acceptance criteria; the product node records form factor, scope, non-goals, and acceptance; the business node records market boundaries, segments, payers, competitive positioning, channels, pricing, cost, market-sizing conventions, unit economics, success metrics, and business gates. A chain's decided only means the current product/business choice was recorded — it is not semantic review, engineering verification, release approval, commercial validity, or causal effect.

2. Find the weakest node; backfill it with research

askovo check ./study --stage design
askovo platforms "home security camera night-alert complaints" --domain hardware --bulk
askovo instruments ./study
askovo collect ./study --platform reddit --query "night alert" --limit 100
askovo analyze ./study --question "night false alerts"

source-plan.csv marks which chain node each route serves via reasoning_nodes, so you never collect just to pump volume. Real collection still requires the Design gate, source authorization, and adapter checks.

analyze only normalizes, deduplicates, computes distributions, frequent candidate terms, and question-matched snippets; it never auto-generates scene, need, feature, or product conclusions.

When the weakest node is not obvious, askovo loop derives the gap from the audit, plans one query per gap and eligible source, runs rounds inside an authorized envelope, and re-audits after each round. Collected records stay review candidates — the loop never assigns an evidence level or edits a judgment.

askovo loop plan ./study
askovo loop authorize ./study --by "researcher"
askovo loop run ./study
askovo loop report ./study

3. Audit both "is the evidence enough" and "is the reasoning broken"

askovo check ./study --stage full --write-report
askovo audit ./study --json
askovo review ./study                 # decision review: readiness, falsifiability, bias, deliverable freshness

Two files, two owners:

• product-reasoning.json: owns the seven-node product semantics and inference rationales;
• demand-judgments.json: owns the evidence-eligibility judgments for demand, solutions, commercial behavior, and counter-evidence.

They join on demand_judgment_id + context_key. Evidence cited by a node must already be registered in the linked demand judgment — you cannot bypass the E1/E2, E3, E4+/E5, counter-evidence, and context gates by editing the chain file. The pain → need edge has a hard floor: a need node can only reach validated with at least one piece of E2 evidence (observed substitution, workaround, or failure behavior); E1 verbal statements alone cap it at needs-validation — saying is not doing.

A complete chain still does not prove product/business success; complete evidence cannot compensate for a missing inference rationale. Automated checks validate structure and configuration only — key semantics, market sizing, and unit economics stay with human and professional review.

4. Project the same chain into role-specific deliverables

askovo deliver ./study --kind decision # decision package: opportunity map / evidence graph / options & trade-offs / decision memo / validation backlog
askovo deliver ./study --kind report   # combined product & business reasoning report
askovo deliver ./study --kind mrd      # market research & analysis → MRD
askovo deliver ./study --kind prd      # requirements research & analysis → PRD
askovo deliver ./study --kind brd      # business analysis → BRD
askovo deliver ./study --kind memo     # product decision memo
askovo boundary ./study --requirements req.md --output ai-prd.md  # F2 boundary audit: Added/Missing/Inflated candidates
askovo cost ./study log --task "audit PRD" --minutes 25           # F4 logged human minutes (optional no-tool baseline)
askovo deliver ./study --kind signoff   # F3 stakeholder sign-off page: conclusions + evidence levels + boundaries + signature block
askovo deliver ./study --kind ops      # user-ops projection
askovo deliver ./study --kind tracker  # behavior, acceptance, and business metric tracking
askovo report ./study                  # research status: 06-report/research-status.md

deliver --kind report is the single writer of the combined product/business report; askovo report writes a separate research-status file. The decision package, MRD, PRD, BRD, and ops views are all projections of one seven-node chain — not parallel sources of truth.

Askovo and SURE

Askovo is the product; SURE is the research and evidence engine underneath.

• Askovo: the chain workspace, five-domain routing, CLI/Skill/MCP, collection, analysis, and role deliverables.
• SURE (Structured User Research with Evidence): method selection, evidence forms and levels, claim boundaries, anti-survivorship bias, safety gates, and judgment constraints.
• All three surfaces share sure_engine.py and the CLI command functions — behavior never forks.

In one line: Askovo handles "reasoning from users to product and business"; SURE makes sure "every step knows how far its evidence actually reaches".

Post-launch growth is handled by Growovo: it consumes askovo's research judgments for positioning and growth (position → build → run), and first-party growth feedback flows back with the same E0–E5 grading — upstream and downstream exchange evidence instead of duplicating research.

Research support capabilities

Method routing

askovo route "how to validate the takeover experience of automotive cockpit voice" --domain automotive --json
askovo methods --domain automotive --stage validation

Automotive routes to clinics, simulators, closed courses, road, or naturalistic driving; consumer goods route to CLT/HUT/repurchase; software routes to usability, beta, A/B, and cohorts.

Platform radar

askovo platforms "home security camera night-alert complaints" --domain hardware --bulk

Answers "where is the data, can it be obtained compliantly, which reasoning node does it help, and what can it not prove". Platform verdicts come as supported, limited, or blocked; where no compliant bulk channel exists, only authorized exports, research APIs, or compliant historical datasets are accepted.

Collection, queues, and reproducibility

• GitHub goes through the official Search API; Reddit through the official Data API; everything else uses authorized exports, historical datasets, or local fixtures.
• Every collection run stores raw envelopes, normalized records, and a manifest recording access basis, rights, counts, discard reasons, restrictions, and bias.
• A SQLite queue supports multiple workers, lease recovery, failure backoff, rate limits, and resumable runs.
• CDP is limited to authorized visible pages on amazon / instagram / bilibili / weibo; X / YouTube and blocked platforms never use it, and captchas, login walls, and platform controls are never bypassed.

See Platforms & connectors and the CLI reference (Chinese).

Six finding types that must not be conflated

E0–E5 grade demand and commercial evidence strength only — they are not a product/business reasoning score. Usability, engineering performance, safety, feasibility, business gates, and release gates each carry their own verification requirements.

Boundaries

• No unauthorized scraping; blocked connectors, login walls, captchas, and platform challenges are never bypassed.
• Platform availability is never treated as sample-represents-population; record counts are never treated as user counts or audience size.
• Feature-mention frequency is not need; purchase intent is not purchase; adoption rate is not product outcome.
• One-time liking is not repurchase; beta, zero complaints, or zero incidents are not safety or release readiness.
• Demand evidence never substitutes for usability, performance, safety, engineering V&V, regulatory, or certification evidence.
• High-risk research stops at S0: the agent may only propose a plan, never instruct execution.
• All deliverables are drafts by default; a passing CLI run never replaces human semantic review, product sign-off, or risk acceptance.

Installation

Not on PyPI yet (checked 2026-10-31); install from source:

pipx install --editable .
askovo --version

Or with venv:

python3 -m venv .venv
.venv/bin/pip install -U pip
.venv/bin/pip install -e .
.venv/bin/askovo demo

The core CLI, Skill, and MCP use only the Python standard library and support Python 3.9–3.12. The optional Workbook XLSX and Amazon HF tools declare openpyxl/datasets separately.

Agent Skill

bash scripts/install-skill.sh
bash scripts/install-skill.sh ~/.codex/skills

MCP

{
  "mcpServers": {
    "askovo": {
      "command": "askovo",
      "args": ["mcp"]
    }
  }
}

MCP exposes askovo_route, askovo_do, askovo_chain, askovo_platforms, askovo_collect, askovo_analyze, askovo_audit, askovo_deliver, and more, sharing behavior with the CLI; collect defaults to dry-run.

Services & support

The engine is free and open source forever: the CLI, Agent Skill, MCP, and the five base domain packs are all MIT, with no feature-crippled edition. The only paid things may be deep domain assets and human delivery — never the engine itself.

Human delivery has no published price list: email tongroy18@gmail.com describing the task (domain, decision question, dates, existing materials, who owns the decision); if it fits, you get a written quote and work starts after confirmation — see the engagement page. Commercial delivery follows the same discipline as the open-source engine: conclusions never outrun the evidence, and semantic review and product sign-off belong to the decision maker. Free support goes through GitHub Issues; no SLA is promised.

Documentation

Docs under docs/ are Chinese for now; this README and llms.txt are the English entry points.

Agent entry points: llms.txt · AGENTS.md · SKILL.md.

Repository layout

skills/askovo/
  SKILL.md                     single-entry protocol and judgment rules
  assets/domain-packs/         five product research packs (never change the chain)
  assets/study-template/       workspace template including product-reasoning
  references/                  research, chain, data, and connector protocols
  templates/                   MRD/PRD/BRD and interview support templates
  scripts/askovo.py            deterministic CLI (single source of behavior)
  scripts/sure_engine.py       SURE support engine and chain scaffolding
  scripts/askovo_mcp.py        MCP shell
docs/                          Chinese product & methodology docs
examples/sample-study/         offline synthetic sample with a complete chain
tests/                         CLI, chain, routing, platforms, queue, MCP tests

Participating & releasing: Contributing · Security policy · Release process · Code of conduct. If Askovo helps you, a star helps more people find it — entirely voluntary, no strings attached.

License

MIT. Third-party components and data-rights boundaries: see LICENSE and docs/connectors.md.

Local document intake (optional Docling adapter)

Study a PDF or Office file without copying it into the chat. This local, opt-in extraction turns a file into Markdown with a SHA-256 provenance sidecar. It does not claim to validate the document, source permission, or any business conclusion.

# Python 3.10+ for current Docling; Askovo's base installation remains dependency-free
pip install docling
askovo document ./research-report.pdf --out ./report-extracted.md
# Read provenance and check source rights before treating its text as evidence.
askovo import ./my-study ./report-extracted.md --source-family imported
askovo audit ./my-study

Plain UTF-8 .txt / .md work without Docling. The resulting .provenance.json records the original file hash and marks the extraction unreviewed. It does not make unsupported public-platform scraping permissible. See feature status.