FinClaw V1 Design Packet — Engineering Readiness Audit
Auditor: Independent Senior Engineer (zero prior context)
Date: 2026-05-15
Scope: 13 documents in projects/finclaw/design/v1/ + foundation + MVP definition
Question: Can I start coding FinClaw V1 tomorrow morning?
1. Executive Summary
Answer: No.
The V1 Design Packet is a coherent and well-structured set of product strategy documents, but it is not an engineering specification package. Every design document explicitly disclaims being "engineering implementation," "API contract," "database migration," or "prompt template." There are no JSON samples, no wireframes, no state machine diagrams, no concrete evaluation prompts, and no runnable artifacts. An engineer could read all 2,500+ lines and still not know what the first database migration, React component, or LangGraph node should look like.
Aggregate implementability score: 2.1 / 5.0 (mean of 11 scored documents)
2. Per-Document Audit
Document 1: projects/finclaw/README.md
What I would produce from this: Navigation index / documentation site router.
Is the spec concrete enough? Yes — this is a thin entry README and it succeeds at that. It maps readers to the right downstream documents.
First blocking question: None. This is an index.
Implementability score: 4/5 — It does its job as an entry point.
FR classification: None. README is not a spec.
Document 2: projects/finclaw/mvp-product-definition.md
What I would produce from this: High-level product requirements document, user persona definitions, and a feature boundary checklist.
Is the spec concrete enough? Partial. The document defines objects with field names (e.g., object, time_context, narratives) but provides no types, no schema, no JSON samples, and no wireframes. The "标准流程" at line 359 is a 9-step text list with no state machine, no sequence diagram, and no API call chain. Section 12 (AI/Agent constraints) is pure prose — no machine-readable constraints.
First blocking question: "What does the Market Cognition Snapshot look like as a concrete JSON object? What are the exact TypeScript interfaces?"
Implementability score: 2/5 — Excellent product context, zero engineering artifacts.
FR classification:
- FR-014 (
mvp-product-definition.md:1-624): 624-line strategy document with thick "what it is/isn't" definitions but no schema, no API signatures, no prompt templates. - FR-017 (
mvp-product-definition.md:105-124): Lists Snapshot "最小字段" as a prose table with no JSON sample, no types, no constraints. - FR-013 (
mvp-product-definition.md:430-438): "AI / Agent 标准化约束" are 6 prose bullet points — none are expressed as schema validation rules, eval assertions, or CI checks.
Document 3: projects/finclaw/design/foundation/product-object-and-advisor-design.md
What I would produce from this: Conceptual object model and advisor role definitions.
Is the spec concrete enough? Partial. The Market Cognition Thread lifecycle states (proposed, active, refresh_due, etc.) are well-defined with entry/exit conditions at lines 32-40. The advisor matrix at lines 147-154 maps roles to skills. However, the "最小字段" table at lines 83-101 lists field names with no types. The advisor output契约 at lines 157-169 has field names but no type system. No JSON examples. No state machine diagram for the lifecycle.
First blocking question: "What is the exact TypeScript interface for MarketCognitionThread? What does evidence_state contain as nested fields?"
Implementability score: 2/5 — Good conceptual model, insufficient for code generation.
FR classification:
- FR-013 (
product-object-and-advisor-design.md:132-144): Advisor "设计原则" are 4 prose sentences with no eval checks or schema constraints to enforce them. - FR-017 (
product-object-and-advisor-design.md:31-40): Thread lifecycle states defined in a table but no state machine diagram, no transition matrix, no event triggers in code. - FR-017 (
product-object-and-advisor-design.md:83-101): "最小字段" table has no JSON sample, no nested object shapes.
Document 4: projects/finclaw/design/foundation/terminology-and-object-naming.md
What I would produce from this: Naming convention linter rules and a glossary component.
Is the spec concrete enough? Yes. This is a terminology baseline and it succeeds. It provides canonical names, Chinese equivalents, and explicit "no longer use" guidance.
First blocking question: None for this document's scope.
Implementability score: 4/5 — Clear enough to enforce in code reviews.
FR classification: None. This is a glossary, not an implementation spec.
Document 5: projects/finclaw/design/v1/v1-prd.md
What I would produce from this: Product requirements for a PRD-to-implementation translation effort.
Is the spec concrete enough? Partial. The Jobs-to-be-Done table at lines 70-77 is clear. The core object descriptions at lines 81-165 are conceptually solid. But UI/UX section 7 (lines 255-296) is a list of areas — "Home / Ask", "Snapshot View", "Thread View" — with no wireframes, no component hierarchy, no interaction specs. Section 10.1 "待实现验收项" at lines 340-350 lists 5 capabilities as "UX 状态 + schema 字段 + evaluation case" but provides none of those.
First blocking question: "Where are the wireframes or Figma files for the 7 screens listed in section 7.1?"
Implementability score: 2/5 — PRD defines "what" but not "how" at any engineering-relevant resolution.
FR classification:
- FR-014 (
v1-prd.md:1-485): 485-line PRD with extensive "非目标" and "失败条件" but UI/UX section is a bullet list of screen names, not designs. - FR-017 (
v1-prd.md:255-296): UI/UX section lists screen names and states but contains zero wireframes, zero component specs, zero interaction patterns. - FR-015 (
v1-prd.md:397-468): "验收标准" section defines 7 acceptance domains but provides no quantitative targets, no first-user cohort size, no time-box, no kill criteria with numbers.
Document 6: projects/finclaw/design/v1/v1-product-object-and-schema-design.md
What I would produce from this: Database schema draft, TypeScript interfaces, Zod validation schemas.
Is the spec concrete enough? Partial — the best of the V1 design packet. Field tables include types (string, enum, array, object, datetime). Lifecycle states are defined with entry/exit conditions. Forbidden fields are explicitly listed at lines 169-186. However, object type is used repeatedly with no nested schema (e.g., cognition_object, time_context, market_context, evidence_state). No JSON examples. No primary/foreign key relationships. No API contract.
First blocking question: "What is the exact nested structure of cognition_object? Is it a discriminated union? A flat object with optional fields?"
Implementability score: 3/5 — Closest to implementable, but object type is a handwave.
FR classification:
- FR-013 (
v1-product-object-and-schema-design.md:169-186): Forbidden fields listed in prose table but no schema-levelnotconstraint, no CI validation rule, no eval assertion that checks for their absence. - FR-017 (
v1-product-object-and-schema-design.md:55-78): Snapshot required fields table has types but zero JSON samples showing a complete snapshot object. - FR-017 (
v1-product-object-and-schema-design.md:94-116): Thread required fields useobjecttype forobject,evidence_statewith no nested shape defined. - FR-008 (
v1-product-object-and-schema-design.md:348-358): Document claims "Acceptance" with 7 checklist items, but the "Open Items" at lines 360-364 admit it's "not API contract," "not database migration," and "not Evaluation Initial Plan."
Document 7: projects/finclaw/design/v1/v1-user-journey-and-interaction-flow.md
What I would produce from this: User state machine, screen flow diagram, interaction specifications.
Is the spec concrete enough? No. The "Primary User States" table at lines 39-50 lists 10 states with prose descriptions but no state machine diagram, no transition events, no guard conditions in code. The Snapshot reading path at lines 121-132 is a numbered list, not a wireframe. Mobile/desktop differences at lines 285-291 are a 6-row summary table. The "Downstream UI / UX Design Checklist" at lines 294-312 lists 15 items that need to be designed — confirming this document is upstream of actual design.
First blocking question: "Where is the state machine diagram for the 10 user states? What events trigger transitions between snapshot_ready → thread_proposed → thread_active?"
Implementability score: 2/5 — Journey map, not implementable interaction spec.
FR classification:
- FR-017 (
v1-user-journey-and-interaction-flow.md:39-50): 10 user states in a table with no state machine diagram, no transition matrix, no event definitions. - FR-017 (
v1-user-journey-and-interaction-flow.md:121-132): Snapshot reading path is a numbered prose list, not a wireframe or component hierarchy. - FR-017 (
v1-user-journey-and-interaction-flow.md:279-291): Mobile/desktop differences described in 6 bullet points, no responsive breakpoint specs, no component behavior definitions.
Document 8: projects/finclaw/design/v1/v1-ui-ux-interaction-design.md
What I would produce from this: React component hierarchy, design system tokens, CSS layout specs.
Is the spec concrete enough? No. The "Core Screens" table at lines 26-37 lists 9 screens with "Required states" but no wireframes. Section 3 "Home / Entry" at lines 38-47 describes layout in 5 bullet points — "主输入框", "最近线程列表", "快速上下文 chips" — with no dimensions, no typography, no spacing. Section 11 admits: "Source File Strategy" says Figma should be used, but no Figma file is referenced or linked. The entire document is a description of what UI should exist, not a specification of what UI to build.
First blocking question: "Where are the Figma files? If they don't exist, can you provide wireframes for at least the 4 core screens (Home, Snapshot, Thread, Checkpoint)?"
Implementability score: 1/5 — Not a UI spec. A UI brief.
FR classification:
- FR-017 (
v1-ui-ux-interaction-design.md:26-37): 9 screens listed with state names but no wireframes, no component specs, no design tokens. - FR-017 (
v1-ui-ux-interaction-design.md:38-47): Home screen described in 5 prose bullets — no layout grid, no dimensions, no interaction patterns. - FR-008 (
v1-ui-ux-interaction-design.md:186-198): Section 11 says "正式 UI 设计源应使用 Figma" but provides no Figma links, no file references, no ownership info.
Document 9: projects/finclaw/design/v1/v1-agent-orchestration-design.md
What I would produce from this: LangGraph state graph, prompt templates, skill function signatures, orchestration DAG.
Is the spec concrete enough? No. The "Layers" table at lines 27-38 lists 7 layers with prose responsibilities. The "Task Routing" table at lines 41-50 maps user intents to routes but provides no routing logic, no prompt template, no code structure. Section 5 at lines 67-80 lists 8 FinSkills but explicitly states: "Initial FinSkills are capability labels, not implementation commitments." No prompt templates. No LangGraph node definitions. No concrete orchestration code structure.
First blocking question: "What is the exact LangGraph state graph? What are the prompt templates for each Skill? What is the function signature for asset-context-summarizer?"
Implementability score: 1/5 — Architectural intent, not an implementable orchestration spec.
FR classification:
- FR-014 (
v1-agent-orchestration-design.md:67-80): Skills are explicitly "capability labels, not implementation commitments" — admission that technical design is not done. - FR-017 (
v1-agent-orchestration-design.md:27-38): 7-layer architecture in a table with no DAG, no state machine, no sequence diagram. - FR-017 (
v1-agent-orchestration-design.md:41-50): Task routing table has no routing logic, no prompt fragments, no conditional branching rules. - FR-013 (
v1-agent-orchestration-design.md:111-127): Boundary Guard behavior described in 8 prose bullets but no eval assertions, no prompt-level constraints, no CI checks.
Document 10: projects/finclaw/design/v1/v1-evaluation-initial-plan.md
What I would produce from this: Evaluation test suite, YAML case files, automated eval pipeline.
Is the spec concrete enough? Partial. The Case Coverage Matrix at lines 28-37 names 6 cases (e.g., Crypto-Asset-Snapshot-Colloquial-01) and maps them to objects and boundary pressures. The scoring draft at lines 39-55 defines A/B/C/D grades. However, there are no actual case YAML files with concrete prompts, no expected outputs, no automated eval scripts. Section 8 provides a YAML template for run results but no actual runs. The document references evaluation/finclaw/cases/README.md but this audit did not find concrete case files.
First blocking question: "Where are the 6 evaluation case YAML files with concrete user prompts and expected object outputs?"
Implementability score: 2/5 — Evaluation framework defined, no actual test cases.
FR classification:
- FR-017 (
v1-evaluation-initial-plan.md:28-37): 6 case names listed but no concrete prompts, no expected outputs, no YAML case files provided. - FR-017 (
v1-evaluation-initial-plan.md:201-221): Run result YAML is a template withstatus: pendingandgrade: null— no actual run evidence. - FR-008 (
v1-evaluation-initial-plan.md:236-240): "Open Items" explicitly states no machine-readable checklist exists, no Evaluation Review/Acceptance Plan exists, no run results exist.
Document 11: projects/finclaw/design/v1/v1-evaluation-review-and-acceptance-plan.md
What I would produce from this: Acceptance checklist, engineering gate criteria, trial sign-off procedure.
Is the spec concrete enough? Partial. The gate scope table at lines 14-19 clearly defines Engineering-start, Trial-start, and Acceptance gates. The acceptance dimensions at lines 62-73 map signals to failure signals. However, the "Quantitative Success Metrics" at lines 75-88 list metrics with no target values (e.g., "Task completion rate for six evaluation cases" — what rate? 80%? 95%?). The timebox at lines 94-103 has duration ranges but no assigned dates. Kill criteria at lines 107-118 are qualitative.
First blocking question: "What are the quantitative targets for the 11 success metrics? What is the minimum task completion rate to pass?"
Implementability score: 2/5 — Gate framework defined, no quantitative targets.
FR classification:
- FR-015 (
v1-evaluation-review-and-acceptance-plan.md:75-88): 11 quantitative metrics listed with no target values, no thresholds, no statistical significance requirements. - FR-015 (
v1-evaluation-review-and-acceptance-plan.md:94-103): Timebox has duration ranges ("3 to 5 working days") but no assigned dates, no owner, no dependency chain. - FR-016 (
v1-evaluation-review-and-acceptance-plan.md:148-152): "Open Items" admit "No actual run evidence," "No reader testing evidence" — document progress masquerading as acceptance plan.
Document 12: projects/finclaw/design/v1/v1-trial-operations-plan.md
What I would produce from this: Trial operations runbook, participant onboarding flow, feedback collection pipeline.
Is the spec concrete enough? Partial. Participant scope at lines 24-39 defines inclusion/exclusion criteria. Trial tasks at lines 60-72 list 3 required + 4 suggested tasks. But there are no concrete participant IDs, no calendar dates, no invitation code mechanism, no feedback form schema, no human review assignment process. The "Open Items" at lines 186-191 explicitly state: "Assign trial owner and reviewer," "Define concrete participant count," "Define exact trial calendar."
First blocking question: "Who is the trial owner? How many participants? What are the exact trial dates?"
Implementability score: 2/5 — Trial framework defined, not an executable operations plan.
FR classification:
- FR-015 (
v1-trial-operations-plan.md:186-191): "Open Items" list missing trial owner, participant count, and exact calendar — critical ops details undefined. - FR-016 (
v1-trial-operations-plan.md:155-171): Trial closeout packet described but document explicitly states "This repository currently has no trial closeout evidence." - FR-017 (
v1-trial-operations-plan.md:75-90): Feedback capture lists 11 feedback types but no form schema, no rating scale, no automated collection mechanism.
Document 13: projects/finclaw/design/task-packets/ (2 files)
What I would produce from this: Task tracking entries in a project management tool.
Is the spec concrete enough? N/A — these are task packet definitions that describe what downstream documents should contain. The downstream documents have been produced (Documents 6 and 7 above). The task packets themselves are planning artifacts, not implementation specs.
First blocking question: None — these are fulfilled.
Implementability score: N/A — Planning documents, not specs.
FR classification: None.
3. Implementation-Blocking Gaps Table
| FR | Severity | file:line | What's missing | Concrete artifact needed |
|---|---|---|---|---|
| FR-017 | P0 | v1-product-object-and-schema-design.md:55-78 | Zero JSON samples for MarketCognitionSnapshot | A snapshot-example.json with all required fields populated for a real crypto asset |
| FR-017 | P0 | v1-agent-orchestration-design.md:67-80 | Skills are "capability labels, not implementation commitments" | Concrete prompt templates and function signatures for each of the 8 FinSkills |
| FR-017 | P0 | v1-ui-ux-interaction-design.md:26-47 | No wireframes, no Figma files, no component specs | Wireframes or Figma frames for Home, Snapshot, Thread, Checkpoint screens |
| FR-017 | P0 | v1-evaluation-initial-plan.md:28-37 | 6 evaluation case names but no concrete prompts or expected outputs | cases/crypto-asset-snapshot-colloquial.yaml with user prompt + expected object fields |
| FR-017 | P0 | v1-user-journey-and-interaction-flow.md:39-50 | 10 user states with no state machine diagram | Mermaid or DOT state machine showing states, events, transitions, guard conditions |
| FR-013 | P0 | v1-product-object-and-schema-design.md:169-186 | Forbidden execution fields listed in prose but no validation logic | Zod/jsonschema not constraints + CI test that asserts forbidden fields are rejected |
| FR-014 | P1 | v1-prd.md:255-296 | UI/UX section is a list of screen names, not designs | Component hierarchy diagram with props interface for each screen |
| FR-014 | P1 | v1-agent-orchestration-design.md:27-38 | 7-layer architecture with no DAG or sequence diagram | LangGraph state graph or sequence diagram showing Task Router → Context Builder → Advisor Planner → ... |
| FR-015 | P1 | v1-evaluation-review-and-acceptance-plan.md:75-88 | 11 success metrics with no quantitative targets | Target values: e.g., "Task completion rate ≥ 80%", "Zero forbidden execution fields" |
| FR-015 | P1 | v1-trial-operations-plan.md:186-191 | Trial owner, participant count, exact calendar undefined | Trial ops runbook with named owner, N=?, start/end dates, recruitment channel |
| FR-017 | P1 | v1-product-object-and-schema-design.md:94-116 | object type used for cognition_object, evidence_state with no nested schema | Nested TypeScript interfaces or JSON Schema for all object-typed fields |
| FR-016 | P2 | v1-evaluation-review-and-acceptance-plan.md:148-152 | "No actual run evidence" — document claims acceptance plan status but has no evidence | At least one simulated evaluation run result populated in the YAML template |
| FR-008 | P2 | v1-ui-ux-interaction-design.md:186-198 | Claims Figma should be used but provides no file references, no links, no ownership | Figma file URL or equivalent design source with version and owner |
| FR-013 | P2 | v1-agent-orchestration-design.md:111-127 | Boundary Guard behavior is 8 prose bullets | Prompt-level system instructions + eval cases that test boundary guard behavior |
| FR-017 | P2 | v1-user-journey-and-interaction-flow.md:279-291 | Mobile/desktop differences in 6 prose bullets | Responsive breakpoint specs, component behavior matrix per breakpoint |
4. Top-5 Questions I Would Ask the FinClaw Owner Before Writing Any Code
Q1 (P0): "Where are the concrete JSON examples?"
The schema design lists 20+ fields across 3 core objects, but there is not a single JSON sample in the entire design packet. Before I write a database migration or TypeScript interface, I need to see at least one complete MarketCognitionSnapshot object populated with real data (e.g., for ETH or BTC). Without this, I cannot validate whether cognition_object should be a flat object, a discriminated union, or a nested structure.
Q2 (P0): "What is the exact tech stack and runtime?"
The documents mention "LangGraph" nowhere, "React" nowhere, "PostgreSQL" nowhere, "FastAPI" nowhere, "OpenAI" nowhere. The Agent Orchestration design refers to "Task Router", "Context Builder", "Advisor Planner" as abstract layers. Are these LangGraph nodes? Are they Python classes? Are they async functions? Are we building a Next.js app? A Python backend? What LLM provider? I need a single-page tech stack decision to even scaffold the repo.
Q3 (P0): "Where are the prompt templates?"
The 8 FinSkills are "capability labels, not implementation commitments." Before I can implement any advisor or skill, I need the actual system prompts, tool schemas, and chain-of-thought instructions. The entire agent layer is a black box from an engineering perspective. Who writes the prompts? Are they in the design packet somewhere I missed?
Q4 (P1): "What are the quantitative acceptance targets?"
The Evaluation Review and Acceptance Plan lists 11 metrics (task completion rate, field presence rate, checkpoint zero-forbidden-fields rate, etc.) but assigns no numbers. Is 70% task completion acceptable? Is 90%? Without targets, I cannot write eval assertions or know when the system is "good enough" for trial.
Q5 (P1): "Who owns the trial, when does it start, and how many users?"
The Trial Operations Plan explicitly lists as "Open Items": trial owner, participant count, exact calendar. Before I write code, I need to know the trial timeline to prioritize features. If trial is in 2 weeks, I need a different scope than if trial is in 2 months. This is a project management blocker, not just a design gap.
5. Engineering Handoff Checklist (Proposal)
Each item below should be implementable by the FinClaw Controller in ≤ 2 days:
Schema & Data Layer
- JSON Sample Pack — Provide 3 complete JSON examples: one
MarketCognitionSnapshot(e.g., BTC), oneMarketCognitionThread(with 2 linked snapshots), onePreExecutionCheckpoint. - Nested Schema Definitions — Replace all
objecttypes with concrete nested structures (e.g.,time_context: { generated_at: ISO8601, coverage_start: ISO8601, coverage_end: ISO8601, stale_boundary: string }). - TypeScript Interface File — A single
types.tsfile with all core interfaces, enums, and discriminated unions. - Zod/jsonschema Validation — Schema validation rules including
notconstraints for forbidden execution fields.
UI/UX Layer
- Wireframes for 4 Core Screens — Home/Entry, Snapshot View, Thread View, Pre-Execution Checkpoint. Can be low-fidelity Balsamiq or Figma frames.
- Component Hierarchy Doc — List of React components with props interfaces for each screen.
- State Machine Diagram — Mermaid/DOT diagram for the 10 user states with events and guard conditions.
Agent & Orchestration Layer
- Skill Prompt Templates — System prompts for each of the 8 FinSkills with input/output JSON schemas.
- LangGraph State Graph — Visual DAG showing nodes (Task Router, Advisor Planner, etc.), edges, and state shape.
- Boundary Guard Test Cases — 10 concrete input/output pairs testing action-adjacent language rejection.
Evaluation Layer
- 6 Evaluation Case YAML Files — Each with:
user_prompt,expected_task_type,expected_fields(list),forbidden_fields(list),minimum_grade. - Quantitative Targets Document — One-pager with target values for all 11 success metrics.
Trial Operations Layer
- Trial Runbook — Named owner, participant count (N), exact dates, invitation mechanism, feedback form schema.
- Sensitive Input Test Suite — 5 test cases: credential rejection, financial context temporary use, profile consent flow, etc.
Appendix: Scoring Methodology
- 5/5 = Can start coding immediately from this document alone
- 4/5 = Clear enough to produce artifacts with minimal clarification
- 3/5 = Partial — can scaffold but need answers for key details
- 2/5 = Thin on implementation detail — need significant design work first
- 1/5 = Architectural intent only — not an engineering spec
- N/A = Not an implementation document (index, glossary, task packet)
Scored documents:
| Document | Score |
|---|---|
| README.md | 4/5 |
| mvp-product-definition.md | 2/5 |
| product-object-and-advisor-design.md | 2/5 |
| terminology-and-object-naming.md | 4/5 |
| v1-prd.md | 2/5 |
| v1-product-object-and-schema-design.md | 3/5 |
| v1-user-journey-and-interaction-flow.md | 2/5 |
| v1-ui-ux-interaction-design.md | 1/5 |
| v1-agent-orchestration-design.md | 1/5 |
| v1-evaluation-initial-plan.md | 2/5 |
| v1-evaluation-review-and-acceptance-plan.md | 2/5 |
| v1-trial-operations-plan.md | 2/5 |
| Mean | 2.1/5 |