AgentSkillsCN

findings-to-plan

将轨迹发现转化为具体的实施计划。适用于收到 findings.md 文件（来自 $analyse-trajectory 或 $playground-explorer）并被要求制定实施计划、将发现映射到代码变更，或把轨迹分析转化为可操作的改进。

SKILL.md
--- frontmatter
name: findings-to-plan
description: >
  Convert trajectory findings into a concrete implementation plan. Use when
  given a findings.md (from $analyse-trajectory or $playground-explorer) and
  asked to create an implementation plan, map findings to code changes, or
  turn trajectory analysis into actionable improvements.

Findings to Plan

Convert findings into an implementation_plan.md with targeted improvements. Not all fixes are code changes — some require updating context generation, others need a human or AI to review and update context docs.

Input

Read data/trajectory/{user_id}/{chat_id}/findings.md. Two formats exist:

  • •analyse-trajectory: Dimension / Turn / Observation / Suggestion / Impact
  • •playground-explorer: Hypothesis / Probe / Observed Trajectory Evidence / Proposed Change / Expected Trajectory Delta

Extract from each finding: title, trajectory references (turn/step/tool_call files), proposed change, impact.

Workflow

1. Verify trajectory evidence

For each finding, read the referenced artifacts:

  • •data/trajectory/{user_id}/{chat_id}/{turn_idx}/turn.md
  • •data/trajectory/{user_id}/{chat_id}/{turn_idx}/tool_calls/*.sql|*.py|*.txt

Confirm the finding's observation matches what actually happened. Drop or flag findings with weak evidence.

2. Explore the agent's environment

Before proposing fixes, understand what the agent actually sees:

  1. •

    Read the context docs the agent used. Findings reference paths like /fact/.../folk1a.md — these map to context/fact/... on disk. Read them to see what information the agent had and what was missing.

  2. •

    Query the database with $psql to understand the actual data. E.g., if the agent used a wrong filter code, run SELECT DISTINCT column FROM fact.table to see what values exist.

  3. •

    Read the subject hierarchy — ls context/subjects/{root}/{mid}/ to see what the agent can discover.

This tells you whether the problem is in the code, the context docs, or the data itself.

3. Trace to existing code

Use the code ownership map to find relevant source files. Read the existing code before proposing changes. Look for:

  • •Existing functions that already do something close
  • •Patterns used elsewhere in the same module
  • •Related logic that would need to stay consistent

4. Design targeted fixes

Categorize each fix:

Code change — modify tool behavior (varro/agent/), prompt (varro/prompts/), app routes, UI, etc. Direct code fixes.

Context generation code — change the generation code in varro/context/ (e.g., get_value_mappings() in fact_table.py should include sentinel values). Context docs will be correct after the next generation run.

Manual context update task — a human or AI assistant reviews and updates specific context docs. Describe the task with clear criteria for what to check and update (e.g., "review all dim table descriptions in data/dst/dim_table_descr/ and ensure hierarchy levels are documented").

For each fix, propose the smallest change that addresses the finding. Prefer:

  • •Adding a parameter to an existing function over creating a new one
  • •Extending existing output over adding a new tool
  • •A one-line prompt addition over a new workflow section

5. Write the plan

Output to data/trajectory/{user_id}/{chat_id}/implementation_plan.md.

Each change should include: what file to edit, what the current code does, what to change and why, how to verify the fix.

Prioritize by impact/effort — smallest high-impact changes first.

Include a Risks / Unknowns section for anything uncertain.

Code ownership map

AreaFiles
Agent promptvarro/prompts/agent/rigsstatistiker.j2
Tool behavior and prompts (Sql, ColumnValues, Jupyter, Read/Write/Edit, Bash)varro/agent/assistant.py
Tool behavior (Bash sandbox)varro/agent/bash.py
Tool behavior (Read/Write/Edit)varro/agent/filesystem.py
Tool behavior (Snapshot)varro/agent/snapshot.py
IPython shellvarro/agent/ipython_shell.py
Agent workspacevarro/agent/workspace.py
Fact table context docsvarro/context/fact_table.py
Dimension table context docsvarro/context/dim_table.py
Subject hierarchy docsvarro/context/subjects.py
Context utilities (fuzzy match)varro/context/utils.py
Data ingestionvarro/data/statbank_to_disk/, varro/data/disk_to_db/
Dimension linkingvarro/data/fact_col_to_dim_table/
Dashboard frameworkvarro/dashboard/
Chat runtimevarro/chat/
Trajectory generationvarro/playground/trajectory.py
Playground CLIvarro/playground/cli.py
UI componentsui/components/, ui/app/
App routesapp/routes/
Teststests/ mirrors varro/ structure
Config / pathsvarro/config.py

Agent environment reference

The agent operates in a sandboxed filesystem. Paths it sees map to disk:

Agent pathDisk pathGenerated by
/subjects/context/subjects/varro/context/subjects.py → create_subjects_data()
/fact/context/fact/varro/context/subjects.py + varro/context/fact_table.py
/dim/context/dim/varro/context/dim_table.py (copies from data/dst/dim_table_descr/)
/geo/context/geo/GeoParquet boundary files
/skills/context/skills/Manual
/dashboard/data/user/{id}/dashboard/Agent-created

Column value parquets: context/column_values/{table}/{column}.parquet

Fact + subject docs are fully regenerable from code. Dim docs are AI-generated (stored in data/dst/dim_table_descr/), requiring an AI generation step to update.

Use $psql to query fact.{table_id} and dim.{table_id} directly.

Relationship to other skills

  • •$playground-explorer — interactive probing, produces findings
  • •$analyse-trajectory — retrospective audit, produces findings
  • •$findings-to-plan — reads findings, traces to code, writes implementation plan