source-first-technical-research

name

source-first-technical-research

description

Source-driven technical research and Chinese reporting for open-source projects, frameworks, libraries, applications, and infrastructure systems. Use when Codex must inspect repositories, explain architecture and implementation from concrete files, analyze algorithms and state transitions, compare multiple software systems by real functional modules, annotate critical source code, prepare diagrams or presentation scripts, or maintain local and Feishu-ready research documents without losing user edits.

Source-First Technical Research

Produce an evidence-backed technical report that helps the reader understand a software system, explain it, answer source-code questions, and reuse its design ideas.

Establish the evidence baseline

1. Define the research question, target audience, compared systems, and required deliverables.
2. Locate every repository and record its remote URL, exact commit, branch, and relevant release.
3. Read repository instructions such as AGENTS.md before inspecting or changing files.
4. Use README and documentation to discover terminology, but verify architectural claims in implementation, tests, schemas, and configuration.
5. Keep three evidence levels in working notes:
   • Confirmed by implementation.
   • Confirmed only by documentation, tests, or examples.
   • Inferred, optional, experimental, or not found.
6. Cite the concrete file, symbol, and commit-pinned link behind each important claim.
7. State access limitations explicitly. Do not silently turn an unverified claim into fact.

Read references/source-verification-checklist.md before repository-wide research or multi-project comparison.

Derive the component map from the target system

Start with these general dimensions, then keep only those that actually exist:

• Entry points and external interfaces
• Core workflow, orchestration, and state machines
• Domain model, data flow, and persistence
• Configuration, resource loading, and dependency wiring
• Extension, plugin, protocol, or integration mechanisms
• Permission, validation, trust boundary, and execution environment
• Concurrency, scheduling, caching, recovery, and observability
• Output, delivery, user interface, and external services

Add domain-specific dimensions only after inspecting the repository. For example, an AI agent may need context, tools, memory, and subagents; a database may need query planning, storage, indexing, and transactions; a compiler may need parsing, intermediate representation, optimization, and code generation.

Do not force every project into one preset architecture. “Absent from core,” “provided by a plugin,” and “delegated to an external system” are valid findings.

Trace real execution before summarizing

Choose one representative user or API input and trace at least:

1. Main path: entry → validation → orchestration → core processing → output.
2. State path: input data → in-memory representation → persistent state or cache → later read.
3. Failure path: error or interruption → retry, rollback, recovery, or surfaced failure.

For every arrow, identify the caller, callee, transferred data, state change, and return value. An arrow must represent a confirmed call, event, read/write, or protocol exchange.

Explain components as software entities

For each important component, answer:

1. What is it: class, service, function, registry, queue, table, event stream, process, or configuration?
2. What concrete problem does it solve?
3. What does it receive?
4. What state does it maintain?
5. What does it provide or produce?
6. Who calls it, and what does it call next?
7. How does its algorithm or state transition work?
8. Which behavior is fixed by developers or operators, selected by an algorithm or model, and chosen by the user at runtime?
9. What happens on failure, restart, timeout, conflict, or rejection?
10. Which source files, tests, and schemas prove the explanation?

Read references/component-analysis.md when the user asks for implementation details, algorithms, state machines, safety boundaries, or a design-ready explanation.

Explain algorithms concretely

For any selection, ranking, scheduling, compaction, caching, routing, or recovery algorithm, state:

• candidate set;
• hard exclusions and validation;
• ordering, score, priority, or transition rule;
• budget, capacity, timeout, or stopping condition;
• protected items and invariants;
• exact output or new state;
• fallback and failure behavior.

Walk one realistic example through these steps. Distinguish source-confirmed behavior from a recommended improvement.

Compare functions, not names

Use the same functional question for every compared project:

• Does the function exist in the core?
• Which software entity implements it?
• What inputs, state, and outputs does it use?
• Is it enabled by default, optional, plugin-provided, or external?
• What algorithm and boundary does it enforce?
• What important function is absent?

Prefer “module present/absent/how implemented” over abstract judgments such as “more complete” or “more flexible.” Use project terminology only after explaining the software entity behind it. End each project paragraph with a direct sentence beginning “核心区别：”.

Write for comprehension

Use Chinese for explanation. Preserve English for project names, source identifiers, and the first occurrence of a useful technical term.

Prefer short paragraphs. Use tables only for exact mappings, feature presence, or repeated comparisons. Use diagrams when flow, hierarchy, state, or containment is materially clearer than prose. Label each node with Chinese and English names and a short statement of its role.

When showing source, select the smallest set of files that covers the core chain. Present file name and stable link, module, reason to read, original code block, adjacent Chinese explanation, caller/callee relationship, and likely review questions.

When the user asks to simplify, remove incidental class names and registration trivia before removing the mechanism that distinguishes the projects.

Read references/report-style-and-delivery.md for report structure, diagrams, code commentary, realistic examples, presentation preparation, and document delivery.

Preserve documents and user edits

Treat the local Markdown report as the canonical editable copy when possible. Before changing an existing local or Feishu document:

1. Read the current content and identify user-authored changes.
2. Edit only the requested section unless restructuring is explicitly requested.
3. Preserve links, comments, diagrams, code blocks, and user wording outside the target.
4. Create a new document or version when the purpose changes, such as teaching, source annotation, comparison, case study, or presentation script.
5. After publishing, verify body content, child-document links, access settings, and public visibility.
6. If direct Feishu editing or synchronization is unavailable, produce paste-ready Markdown locally and state the limitation.

Final quality gate

Verify that:

• every important arrow and claim has source evidence;
• no project-specific term appears before it is explained;
• defaults, optional features, plugins, and examples are clearly separated;
• configuration, automatic runtime decisions, model decisions, and user choices are not conflated;
• an application convention is not described as an enforced security boundary;
• in-memory state, persistent facts, cache, snapshots, and derived views are not conflated;
• feature comparisons state what exists, what is absent, and how it is implemented;
• source links are pinned to the researched commit;
• the final answer names every created or updated artifact.