Skip to content

zy839971925-zyy/Agent--deep-research-Workflow-Skills / skills/reasoning-workflow

reasoning-workflow

Verified

Default silent workflow for everyday questions, research, writing, design and engineering. Match effort to the request, resolve costly ambiguity, find specialist resources and verify the requested outcome. Explicitly selectable with “调用我的 workflow skills”.

FileKindSize
CHANGELOG.mdmarkdown10.2 KB
LICENSE.txtmarkdown1.0 KB
README.mdmarkdown3.0 KB
RELEASE.jsonconfig509 B
SHA256SUMSother17.9 KB
SKILL.mdskill md5.4 KB
TEST_REPORT.mdmarkdown11.4 KB
UPGRADE.mdmarkdown13.1 KB
agents/openai.yamlconfig386 B
assets/icon.svgother3.1 KB
docs/BUILD_SOURCE_COMPARISON.jsonconfig25.1 KB
docs/BUILD_SOURCE_COMPARISON_2.1.1.jsonconfig6.0 KB
docs/LEGACY_ENTRY.mdmarkdown17.2 KB
docs/MAIN_INTEGRATION.mdmarkdown3.3 KB
docs/PACKAGE_VALIDATION.jsonconfig412 B
docs/PACKAGE_VALIDATION_2.1_BASELINE.jsonconfig316 B
docs/PATCH_2.1.1.diffother48.3 KB
docs/RELEASE_2.1.1.zh-CN.mdmarkdown7.5 KB
docs/RELEASE_2.2.0.zh-CN.mdmarkdown3.7 KB
docs/RELEASE_3.0.0.zh-CN.mdmarkdown8.4 KB
docs/RELEASE_3.0.1.mdmarkdown824 B
docs/RELEASE_3.0.1.zh-CN.mdmarkdown699 B
docs/RELEASE_3.1.0.mdmarkdown770 B
docs/RELEASE_3.1.0.zh-CN.mdmarkdown808 B
docs/RELEASE_3.2.0.mdmarkdown3.2 KB
docs/TECHNICAL_ARCHITECTURE.mdmarkdown13.4 KB
docs/TECHNICAL_ARCHITECTURE.zh-CN.mdmarkdown11.8 KB
docs/TEST_REPORT_2.1_BASELINE.mdmarkdown4.6 KB
evals/cross_task_cases.jsonconfig21.7 KB
evals/fixtures/architecture-project/README.mdmarkdown598 B
evals/fixtures/architecture-project/src/export.pyscript251 B
evals/fixtures/architecture-project/src/storage.pyscript538 B
evals/fixtures/architecture-project/tests/test_storage.pyscript374 B
evals/fixtures/checkpoint-evidence-mismatch/archive/recommendation-v1.mdmarkdown429 B
evals/fixtures/checkpoint-evidence-mismatch/deliverables/recommendation.mdmarkdown521 B
evals/fixtures/checkpoint-evidence-mismatch/state/checkpoint.mdmarkdown1.1 KB
evals/fixtures/checkpoint-evidence-mismatch/verification/acceptance-review.jsonconfig1.1 KB
evals/fixtures/dependency-resume/completed/local-export-analysis.mdmarkdown412 B
evals/fixtures/dependency-resume/drafts/privacy-section.mdmarkdown144 B
evals/fixtures/dependency-resume/drafts/provider-sync.mdmarkdown196 B
evals/fixtures/dependency-resume/drafts/recovery-section.mdmarkdown158 B
evals/fixtures/dependency-resume/materials/provider-key-management-v2.mdmarkdown569 B
evals/fixtures/dependency-resume/state/checkpoint.mdmarkdown1.3 KB
evals/fixtures/dependency-resume/state/dependency-map.mdmarkdown671 B
evals/fixtures/long-horizon-workspace/archive/docs/sync-options.mdmarkdown247 B
evals/fixtures/long-horizon-workspace/notes/unrelated-ai-scheduler.mdmarkdown209 B
evals/fixtures/long-horizon-workspace/research/architecture/sync-options.mdmarkdown926 B
evals/fixtures/long-horizon-workspace/state/checkpoint.mdmarkdown1.2 KB
evals/fixtures/qualitative-interview-mixed-views.jsonconfig2.3 KB
evals/fixtures/root-cancellation-late-result/README.mdmarkdown249 B
evals/fixtures/root-cancellation-late-result/state/root.jsonconfig222 B
evals/fixtures/root-cancellation-late-result/worker/draft.mdmarkdown136 B
evals/fixtures/root-cancellation-late-result/worker/late-result.jsonconfig233 B
evals/fixtures/runtime-revision-mismatch/README.mdmarkdown417 B
evals/fixtures/runtime-revision-mismatch/artifacts/recommendation-draft.mdmarkdown280 B
evals/fixtures/runtime-revision-mismatch/state/checkpoint.jsonconfig878 B
evals/fixtures/runtime-revision-mismatch/state/current-environment.jsonconfig399 B
evals/fixtures/runtime-revision-mismatch/state/dependency-map.jsonconfig516 B
evals/fixtures/search-yield-control.jsonconfig2.1 KB
evals/v3-functional-scenarios.mdmarkdown34.5 KB
families/audit-verification.mdmarkdown1.1 KB
families/core-reasoning.mdmarkdown2.0 KB
families/decision-analysis.mdmarkdown698 B
families/deep-research.mdmarkdown2.2 KB
families/execution-control.mdmarkdown1.5 KB
families/workflow-learning.mdmarkdown500 B
meta/README.mdmarkdown26.7 KB
meta/README.zh-CN.mdmarkdown26.4 KB
references/change-governance-and-effectiveness.mdmarkdown12.0 KB
references/clarification-gate.mdmarkdown6.9 KB
references/comparative-synthesis.mdmarkdown3.2 KB
references/decision-and-recommendation.mdmarkdown6.6 KB
references/domain-patterns.mdmarkdown4.2 KB
references/engineering-delivery.mdmarkdown2.8 KB
references/evidence-and-provenance.mdmarkdown7.3 KB
references/formal-review-and-audit.mdmarkdown7.4 KB
references/harness-integration.mdmarkdown7.5 KB
references/harness-profiles.mdmarkdown11.8 KB
references/host-adapter.mdmarkdown11.8 KB
references/human-context-and-interpretation.mdmarkdown3.9 KB
references/hypotheses-and-bias-control.mdmarkdown6.2 KB
references/information-target-navigation.mdmarkdown7.4 KB
references/inquiry-and-research.mdmarkdown9.1 KB
references/measurement-and-operationalization.mdmarkdown3.1 KB
references/model-adaptation.mdmarkdown7.5 KB
references/multimodal-and-data.mdmarkdown3.4 KB
references/problem-framing-and-effort.mdmarkdown8.6 KB
references/reasoning-structure-and-decomposition.mdmarkdown5.5 KB
references/relationships-and-systems.mdmarkdown4.2 KB
references/research-modes-and-methods.mdmarkdown17.1 KB
references/research-to-report.mdmarkdown3.8 KB
references/retrieval-and-observation.mdmarkdown14.4 KB
references/runtime-and-delegation.mdmarkdown8.9 KB
references/semantic-state-contract.mdmarkdown5.7 KB
references/specialist-resources.mdmarkdown2.8 KB
references/state-model-and-invariants.mdmarkdown7.1 KB
references/synchronization-and-recovery.mdmarkdown9.6 KB
references/synthesis-execution-and-verification.mdmarkdown6.7 KB
references/task-strategies.mdmarkdown4.9 KB
references/time-scenarios-and-forecasting.mdmarkdown3.6 KB
references/traceability-and-integrity.mdmarkdown6.2 KB
references/ultra-research.mdmarkdown9.1 KB
references/worked-examples.mdmarkdown5.1 KB
references/workflow-learning-and-capa.mdmarkdown4.4 KB
references/writing-for-the-reader.mdmarkdown1.7 KB
routing-index.jsonconfig18.0 KB
schemas/capability-snapshot.schema.jsonconfig1.1 KB
schemas/checkpoint-manifest.schema.jsonconfig5.6 KB
schemas/delivery-manifest.schema.jsonconfig4.9 KB
schemas/dual-verification.schema.jsonconfig2.6 KB
schemas/edge-policy.jsonconfig3.8 KB
schemas/event.schema.jsonconfig1.9 KB
schemas/execution-node-state.schema.jsonconfig2.7 KB
schemas/execution-plan.schema.jsonconfig5.7 KB
schemas/execution-schedule.schema.jsonconfig3.7 KB
schemas/learning-record.schema.jsonconfig4.5 KB
schemas/raw-record.schema.jsonconfig3.3 KB
schemas/review-bundle.schema.jsonconfig1.6 KB
schemas/task-profile.schema.jsonconfig4.2 KB
schemas/work-state.schema.jsonconfig90.9 KB
schemas/worker-proposal.schema.jsonconfig3.1 KB
scripts/build_distribution.pyscript1.7 KB
scripts/check_report_evidence.pyscript3.6 KB
scripts/harness_bridge.pyscript9.2 KB
scripts/host_adapter.pyscript2.1 KB
scripts/learning_core.pyscript6.3 KB
scripts/prepare_task.pyscript2.6 KB
scripts/reference_core.pyscript1.4 KB
scripts/requirements.txtmanifest37 B
scripts/retrieve_learnings.pyscript1.6 KB
scripts/route_resources.pyscript4.1 KB
scripts/route_task.pyscript1.0 KB
scripts/routing_core.pyscript6.5 KB
scripts/runtime_core.pyscript36.4 KB
scripts/semantic_core.pyscript14.9 KB
scripts/validate_delivery.pyexecutablescript10.4 KB
scripts/validate_dual_verification.pyscript3.1 KB
scripts/validate_events.pyscript2.8 KB
scripts/validate_learning.pyscript718 B
scripts/validate_raw.pyscript3.0 KB
scripts/validate_runtime.pyexecutablescript2.5 KB
scripts/validate_state.pyexecutablescript3.3 KB
scripts/validate_workflow.pyscript9.0 KB
tests/audit_repro/adversarial_probes.pyscript6.9 KB
tests/audit_repro/original_2.1_observations.jsonconfig4.4 KB
tests/check_package.pyscript6.1 KB
tests/fixtures/R2-orthogonal-gap-missing-family_profile.jsonconfig464 B
tests/fixtures/R4-light-action-governance-reference-filter_profile.jsonconfig450 B
tests/fixtures/R4-light-high-consequence-reference-filter_profile.jsonconfig482 B
tests/fixtures/answer.txtmarkdown21 B
tests/fixtures/baseline_manifest.jsonconfig871 B
tests/fixtures/baseline_state.jsonconfig2.3 KB
tests/fixtures/causal-search-source-pack.jsonconfig4.9 KB
tests/fixtures/failed_review_record.jsonconfig498 B
tests/fixtures/hybrid_two_cycle_input.jsonconfig1.9 KB
tests/fixtures/learning_intrinsic_flag_false.jsonconfig692 B
tests/fixtures/legal_parallel_independent_input.jsonconfig1.9 KB
tests/fixtures/mixed_plan_schedule_cycle_input.jsonconfig1.9 KB
tests/fixtures/old_answer.txtmarkdown31 B
tests/fixtures/parallel_self_cycle_input.jsonconfig1.2 KB
tests/fixtures/parallel_two_cycle_input.jsonconfig1.9 KB
tests/fixtures/resume_safe_cancelled_input.jsonconfig2.1 KB
tests/fixtures/single_review_record.jsonconfig297 B
tests/fixtures/standard_profile.jsonconfig427 B
tests/fixtures/ultra_delegated_profile.jsonconfig469 B
tests/results/cli_receipts.jsonconfig28.3 KB
tests/results/cli_receipts_2_1_1.jsonconfig35.8 KB
tests/results/independent_tamper_recheck.jsonconfig373 B
tests/results/original_probes_after.jsonconfig7.3 KB
tests/results/regression_2_1_1.logother8.0 KB
tests/results/summary.jsonconfig239 B
tests/results/summary_2_1_1.jsonconfig306 B
tests/run_all.pyscript2.0 KB
tests/run_regression.pyscript38.6 KB
tests/test_2_1_1.pyscript12.0 KB
tests/test_3_2.pyscript4.1 KB
tests/test_harness_bridge_reconciliation.pyscript6.9 KB

docs/TECHNICAL_ARCHITECTURE.md

View on GitHub
# Technical architecture and execution boundaries

**Design baseline:** Reasoning Workflow 3.0.0, merged into `main` on 2026-10-24. This report describes the repository design; it is not a claim that any host activated the Skill or that model behavior improved. The comparison baseline for the 3.0.0 work was 2.1.1 (`97efc58`); 2.2.0 was a local intermediate candidate.

[中文技术架构报告](TECHNICAL_ARCHITECTURE.zh-CN.md) · [English README](https://github.com/zy839971925-zyy/Agent--deep-research-Workflow-Skills/blob/e65072c/README.md) · [中文 README](https://github.com/zy839971925-zyy/Agent--deep-research-Workflow-Skills/blob/e65072c/README.zh-CN.md)

## 1. Architectural intent

Reasoning Workflow is a portable, model-facing method plus optional deterministic preparation and validation tools. It is not itself a model, a web-search engine, a permission system, a durable task service, or an external-action executor. The host supplies activation, model runtime, tools, identity, permissions, persistence, and any actual execution enforcement.

The architecture aims to keep four responsibilities distinct:

1. The host decides whether and how the Skill is activated and which tools are actually available.
2. The workflow chooses a proportionate research/execution method and the next useful step.
3. Evidence and runtime receipts establish what was actually read, executed, or completed.
4. Static checks and protocol scenarios validate repository artifacts and specify expected behavior; only a model-in-the-loop evaluation can measure whether a model follows the workflow.

```mermaid
flowchart TD
  U[User request] --> H[Host activation and live capability boundary]
  H -->|Skill selected or instruction supplied| S[Portable SKILL.md]
  S --> P[Frame outcome, risk, effort and evidence gaps]
  P --> R[Routing index and on-demand Family/method]
  R --> M[Research, decision or execution method]
  M --> E[Underlying evidence and observed tool results]
  E --> V[Claim, dependency and acceptance checks]
  V --> O[Answer, artifact, partial handoff or focused question]
  H -. optional .-> X[Trusted host adapter / enforcement]
  X -. live receipts and permission checks .-> E
```

The dotted adapter is optional and host-owned. Instructions can direct a model to request or use a tool; only an actual host integration can enforce the call, check live permission, record the effect, or guarantee persistence.

## 2. Skill activation and routing

### Activation is a host responsibility

Automatic invocation has two separate stages:

- **Activation:** an always-on host instruction, native skill discovery/selector, or trusted front router makes this Skill available for a turn. This stage cannot be guaranteed by a file inside a Skill that the host has not loaded.
- **Method routing:** once the Skill is present, its entry guidance classifies the task and loads only relevant methods/references. The optional `prepare_task.py` helper normalizes a supplied profile and prepares a route; it does not inspect arbitrary natural-language turns or activate a host Skill by itself.

A deployment that promises silent invocation on every user request must therefore configure and test the host-level activation rule. Best-effort native discovery is not an every-turn guarantee. Explicit wording such as “use/call my workflow skills” can be mapped to the same workflow entry; quoted or discussed wording is not itself an invocation. Host-specific instructions must preserve stronger platform rules and available-tool limits.

```mermaid
flowchart LR
  A[Host always-on rule / native selector] --> B[Skill becomes available]
  B --> C[Light-to-Ultra effort selection]
  C --> D[Relevant Family and reference routing]
  D --> E[Current task execution]
  F[prepare_task.py] -. optional profile preparation .-> D
```

`routing-index.json` describes routeable Families, methods, triggers, references, and resource needs. The Lightweight path can answer simple questions without loading the research library. Deeper tiers increase effort only when ambiguity, stakes, dependencies, or expected answer gain justify it; they do not grant more authority or imply automatic delegation.

## 3. Portable and Modular editions

- **Portable** (`skills/reasoning-workflow/`) is the canonical package. It includes the root entry, routing index, Families, references, JSON schemas, optional Python helpers, fixtures, and tests. It is the complete choice when deterministic route preparation and cross-Family state matter.
- **Modular** (`modular/`) splits the six instruction-focused Families for hosts with their own skill discovery/routing. It mirrors selected references at their point of use. It does not reproduce Portable's Python router, schemas, runtime helper layer, or cross-Family state as an independent execution service.

The mirrored texts and relative links are checked as repository/package contracts. They are still guidance read by a model, not separately running agents.

## 4. Research and causal web retrieval

The research path begins with an information need, not a keyword quota. It distinguishes real-world/empirical questions, pre-build technical architecture questions, and linked hybrid questions. The evidence surface is chosen by where the uncertainty can be observed: user-provided material, the live repository/runtime, structured records, public sources, or an authorized experiment.

For causal questions, a proposed chain remains a set of hypotheses. The retrieval method selects one answer-changing edge and targets the evidence that can discriminate among explanations. It may search distinct roles—effect/comparison and design, mechanism and timing, confounding/selection/reverse causality, and boundary/null/adverse evidence—only when each can change the answer. A source's terms, measures, study design, population, cited work, or registry identifier can update the next query. The model then reads underlying material, checks the exact scope and design, updates which claim/link is supported, contradicted, or unresolved, and stops when another route has low expected answer gain.

```mermaid
flowchart LR
  C[Provisional causal map] --> G[Choose one material link / uncertainty]
  G --> Q[Query for a discriminating observation]
  Q --> S[Inspect source and learn terminology/design]
  S --> N[Adapt query or evidence route]
  N --> T[Update claim, scope and dependencies]
  T -->|important gap remains| G
  T -->|low expected gain / bounded evidence| F[Qualified synthesis]
```

Queries are retrieval moves, not evidence. Search snippets, ranking, phrase operators, one study, a plausible mediator, or a citation trail alone do not verify a causal chain. Prefer direct observation and primary material where appropriate; evaluate population, comparator, design assumptions, outcome and time scope. Citation chaining can discover a missing route but correlated papers are not independent confirmation. Report search scope and access limits proportionately; a failed or empty query does not establish absence.

The implementation is in [Retrieval and observation](../references/retrieval-and-observation.md), with a concrete tutoring example, search-method bibliography, and the protocol-only [V3-WS scenario](../evals/v3-functional-scenarios.md#v3-ws-causal-chain-web-search-beyond-keyword-matching). These sources inform the method; they do not prove that an LLM performs better with it.

## 5. Clarification and architecture decisions

The clarification gate separates four kinds of missing information: user intent/priority, existing project evidence, external facts, and safe routine details. Check only the available sources relevant to a missing dependency and capable of changing the answer. Ask only when the unresolved choice belongs to the user, changes the recommendation or required output, and cannot be handled with a clear conditional answer or reversible assumption. Continue independent work. A reply to a question does not grant permission for a separate external action.

For development-before-build research, inspect the real repository and constraints first. When a decision depends on quality attributes (for example privacy, offline use, recovery, latency, maintenance), express those as concrete scenarios and compare viable designs against them. Keep a concise architecture decision record for durable, costly-to-reverse choices; use a reversible prototype/benchmark only when it can discriminate a material engineering assumption. Research recommendations are not implementation authorization.

## 6. Long-running work, recovery, and delegation

The workflow uses task state, acceptance conditions, dependencies, checkpoints, artifacts, and delivery manifests when task duration or consequence warrants them. It does not prescribe one persistence backend. On resume, reconcile the root goal and latest user instruction with the current checkpoint, repository/workflow revision, live host/tools/permissions, relevant upstream sources, and actual artifacts. If a path is stale, relocate candidate files in the authorized workspace and compare their identity/version/content before choosing; unknown is not unchanged or absent. Recompute only results dependent on changed conditions.

A child report, planned command, or “complete” checkpoint does not establish the external result. A partial handoff retains open acceptance conditions. A canceled root is not reopened by a late worker result; cancellation also does not prove that an already submitted external side effect stopped. For an uncertain write, reconcile the destination before any retry. These are protocol requirements; if a host does not persist or enforce the relevant state, the capability remains a limitation rather than a guarantee.

## 7. Verification layers and what they establish

| Layer | Current candidate evidence | What it establishes | What it does not establish |
| --- | --- | --- | --- |
| Static / contract tests | 34 repository tests and 69 Portable regression tests have passed for the candidate after the latest recorded edits; final package run must match the delivered archive. | Schemas, deterministic helpers, fixtures, links, routing references, and package contracts meet their tested assertions. | Natural-language model compliance, better research answers, or real host integrations. |
| Functional scenario protocols | 21 cross-task cases and 17 V3 scenarios describe observable checks; they are marked protocol-only. | Testable expected actions, artifacts, handoffs, and failure conditions are specified. | That any model has executed or passed them. |
| Model-in-the-loop comparison | Not run. | Nothing yet. | No claim that model quality, search quality, adherence, cost, latency, or long-task success improved. |
| Host integration | Optional interfaces are documented; actual availability depends on deployment. | A trusted host may implement and test the described contracts. | This repository alone does not enforce global activation, permissions, external writes, payment, durable storage, or rollback. |

For a defensible effectiveness claim, run the same model, host, tools, task set, and budgets against the baseline and candidate; blind-score final answers and observable retrieval/clarification/recovery traces with separate metrics. Protocol and static test counts are not model-performance scores.

## 8. Repository map

- [`../SKILL.md`](../SKILL.md): model-facing entry and workflow contract.
- [`../routing-index.json`](../routing-index.json): routes, triggers, resource requirements, and references.
- [`../families/`](../families/): on-demand task Families.
- [`../references/`](../references/): detailed methods, including causal retrieval, clarification, host profiles, and recovery.
- [`../evals/`](../evals/): cross-task cases, V3 protocol scenarios, and fixtures.
- [`../scripts/`](../scripts/): optional deterministic preparation/build helpers.
- [`../tests/`](../tests/): static, schema, CLI, and package-contract tests.
- [`../../../modular/`](https://github.com/zy839971925-zyy/Agent--deep-research-Workflow-Skills/blob/e65072c/modular/README.md): focused instruction-only edition.
- [`../TEST_REPORT.md`](../TEST_REPORT.md), [`RELEASE_3.0.0.zh-CN.md`](RELEASE_3.0.0.zh-CN.md): recorded verification and release notes.

## References

- Software Engineering Institute, Carnegie Mellon University. [Architecture Tradeoff Analysis Method (ATAM)](https://www.sei.cmu.edu/library/architecture-tradeoff-analysis-method/). An architecture evaluation method; the workflow borrows a light scenario/trade-off framing, not a claim to perform a formal ATAM review.
- Bates, M. J. (1989). [The Design of Browsing and Berrypicking Techniques for the Online Search Interface](https://pages.gseis.ucla.edu/faculty/bates/articles/berrypicking.pdf). *Online Review*, 13(5), 407–424.
- Cochrane Handbook. [Chapter 4: Searching for and selecting studies](https://www.cochrane.org/authors/handbooks-and-manuals/handbook/current/chapter-04). Systematic-review search methods are not a mandatory quota for ordinary queries.
- Hernán, M. A. et al. (2024). [Causal Inference About the Effects of Interventions From Observational Studies in Medical Journals](https://jamanetwork.com/journals/jama/fullarticle/2818746). *JAMA*.
- Kahneman, D., & Klein, G. (2009). [Conditions for intuitive expertise: A failure to disagree](https://pubmed.ncbi.nlm.nih.gov/19739881/). *American Psychologist*, 64(6), 515–526.

For the broader methods bibliography and additional limitations, see [Research modes and methods](../references/research-modes-and-methods.md) and [Retrieval and observation](../references/retrieval-and-observation.md).
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall