mirofish-guide

name	mirofish-guide
description	Companion skill for the MiroFish multi-agent simulation engine. Use when planning or running MiroFish simulations, writing source material or simulation requirements, debugging graph/entity/profile/config/runtime/report stages, evaluating run quality, validating model or proxy routes, interpreting generated artifacts, or maintaining a repository of MiroFish best practices.

MiroFish Guide Skill

Use this skill when the task touches MiroFish operations, documentation, experiments, or repository maintenance.

MiroFish is a multi-stage engine:

1. source material is uploaded and chunked;
2. Zep graph extraction runs;
3. entities are filtered for simulation;
4. OASIS profiles are generated;
5. simulation config is generated by an LLM;
6. Twitter and Reddit environments run;
7. a report agent analyzes the result.

The best way to work on MiroFish is to identify the stage first, then inspect the artifacts and constraints for that stage.

Reference Routing

Load only the file you need:

• references/workflow.md Use for end-to-end architecture, stage ownership, and code-grounded defaults.

• references/debugging.md Use for setup problems, missing artifacts, weak runs, report issues, or proxy problems.

• references/graph-build-runbook.md Use for sparse ontology output, graph build failures, Zep ingestion trouble, or entity-normalization issues.

• references/seed-templates.md Use for reusable source-material patterns and stronger simulation requirements.

• references/experiments.md Use for empirical tuning observations, model comparisons, and cost-quality tradeoffs.

• references/operator-workflow.md Use for the practical operator loop: pilot run, artifact checks, scaling, and post-run audit.

• references/runtime-forensics.md Use when a run technically completed but you need to judge whether it produced meaningful multi-agent behavior.

• references/report-audit.md Use when verifying report claims against raw artifacts and tool logs.

• references/evidence-taxonomy.md Use when classifying claims or verifying whether a report assertion is actually supported.

• references/evaluation-rubric.md Use when scoring simulation quality or report quality.

• references/experiment-protocol.md Use when planning a reproducible comparison across models, prompts, or runtime settings.

• references/model-proxy-guidance.md Use when validating model routes, OpenAI-compatible proxies, or structured-output reliability.

• references/anti-patterns.md Use when preventing common operator mistakes before they waste time or API budget.

• references/glossary.md Use for short definitions of MiroFish, OASIS, Zep, GraphRAG, and report-stage terms.

• references/project-context.md Use for background questions: who backs/built MiroFish, how popular it is, release timeline, how much to trust its predictions, the local-deployment forks, and how it compares to other simulators. Dated snapshot; the rest of the guide is version-neutral.

Operating Rules

1. Separate code-confirmed facts from experiment-confirmed observations.
2. Prefer fixing source material and simulation requirements before patching engine internals.
3. Debug from generated artifacts first, not from vague impressions of the final report.
4. Do not assume round count equals reasoning depth.
5. Treat the report as a summary layer and verify important claims against raw artifacts.

What Usually Matters Most

Source material

This is the main quality lever.

Strong input usually contains:

• named stakeholders;
• explicit relationships between actors;
• dates, numbers, and concrete events;
• multiple perspectives on the same topic;
• one clear scenario instead of mixed unrelated topics.

Weak input usually produces weak graphs, generic personas, and shallow reports.

Simulation requirement

The requirement should say what the engine should explore, over what timeframe, and with which focal variables.

Good requirement pattern:

[topic] over [timeframe].
Focus on [3-5 factors].
Watch for [risks, scenarios, or stakeholder reactions].

Bad requirement pattern:

What will happen?

Agent quality

MiroFish does not start from a handcrafted agent roster. Agent quality depends on:

• extracted entities;
• enriched context from the graph;
• profile generation quality;
• model quality.

If agents look generic, inspect entity relevance before blaming the profile layer.

Debugging Heuristics

If the run is weak

Check in this order:

1. source material
2. graph quality
3. filtered entities
4. generated profiles
5. simulation config
6. runtime artifacts
7. report logs

If the simulation ends too quickly

Inspect:

• state.json
• simulation_config.json
• run_state.json
• per-platform actions.jsonl
• per-platform simulation databases

Fast completion can mean the environment only produced initial actions and did not do much per-round reasoning.

If a proxy behaves strangely

Inspect request and response compatibility separately from model quality.

Known failure pattern:

• assistant output may need to be represented as output_text rather than input_text in OpenAI-compatible flows.

If environment variables look ignored

Remember:

• MiroFish loads the project root .env
• loading uses override semantics

So the root .env can silently replace values you thought were inherited from a parent process.

High-Value Facts

• the engine accepts pdf, md, txt, and markdown uploads;
• graph build uses chunking before Zep ingestion;
• generated runtime artifacts live under backend/uploads/simulations/<simulation_id>/ in a MiroFish checkout;
• report artifacts live under backend/uploads/reports/<report_id>/ in a MiroFish checkout;
• report generation is often the most reasoning-heavy stage;
• the report agent uses tool-backed section generation and logs its work to agent_log.jsonl.

When Maintaining This Repository

Keep the repository strict about evidence:

• guide files should stay compact;
• detailed facts belong in references/;
• experiment notes should stay clearly marked as empirical;
• if upstream MiroFish changes behavior, update the affected stage rather than scattering edits everywhere.