meeting-lab/AGENTS.md

AGENTS.md

Practical instructions for coding agents working in Meeting Lab.

Project Purpose

Meeting Lab extracts and structures organizational knowledge from meeting recordings. It is an experimental local discussion analyzer, not merely a one-step meeting-protocol generator.

Successful approaches may later move into the Meeting Assistant project.

Current Pipeline

Current and intended flow:

Audio
-> Whisper
-> cleanup
-> normalization
-> chunking
-> local chunk extraction
-> consolidation
-> Canonical Meeting Knowledge
-> Output Views

Status:

• Implemented: Whisper JSON cleanup script, normalization, technical chunking, local chunk extraction, interim Markdown protocol builder.
• Experimental/prototype: topic segmentation and review tooling.
• Planned: consolidation, Canonical Meeting Knowledge implementation, final Output Views.

Architectural Principles

• Canonical Meeting Knowledge is the intended semantic source of truth.
• Working Protocol / Arbeitsprotokoll, Distribution Protocol / Verteilerprotokoll and Knowledge Objects / Wissensdatenbankeintrag are parallel output views.
• Output views must not silently change meaning. They may select, condense or render information for an audience, but not invent new semantics.
• Extraction, consolidation, synthesis and rendering are separate concerns.
• Prefer small, testable processing stages over one monolithic LLM prompt.
• Current extraction strategy is one normalized chunk per LLM call.
• Do not expand context windows or redesign the extraction strategy without an explicit experiment.
• Deterministic stages should remain deterministic where possible.

Prompt Engineering Rules

The Gold Standard corpus is the reference specification. Follow Rules 1-11 from tests/gold/PROMPT_ENGINEERING_METHODOLOGY.md:

1. Make only one prompt change per iteration.
2. Optimize only one target gold test case at a time.
3. Validate every prompt modification immediately.
4. Accept a prompt change only if it improves the target and causes no regressions in previously passing gold tests.
5. Never modify expected.json merely to make a prompt pass.
6. Prompt engineering edits prompt files only; Python code changes require a separate explicit task.
7. Maintain a prompt evolution log for every iteration.
8. Stop arbitrary iterations if small changes do not improve the test; analyze the root cause.
9. Avoid gold-test overfitting. Prompt changes must generalize and must not special-case one transcript.
10. Stop after two consecutive non-improving prompt iterations and classify the root cause.
11. Verify whether the target gold test has objectively unique ground truth before changing a prompt for unexpected behavior.

Current documented Prompt Version 2 decision baseline:

• decision_simple: passing
• decision_deferred: passing
• decision_none: passing

LLM Execution Safety

• Never start a full multi-chunk LLM run unless explicitly requested.
• Before any LLM run, state the model, inputs, expected LLM-call count and output location.
• Do not retry LLM calls automatically unless explicitly allowed.
• Do not download models automatically.
• Prefer small-scope validation runs.
• Never use generated output as committed source data.
• Preserve raw model responses when diagnosing parser or truncation failures.
• Do not run Ollama from unit tests.

Development Rules

• Make small, focused changes.
• Preserve the existing architecture unless a redesign is explicitly requested.
• Add regression tests for bugs.
• Run non-LLM tests before committing when code changes are made.
• Do not commit generated transcripts, audio, extraction JSON, protocol output or temporary files.
• Report files changed, tests run and assumptions.
• Do not commit or push unless explicitly requested.

Repository Conventions

• README.md: project overview and current high-level status.
• docs/: architecture, pipeline, data model and output-view documentation.
• prompts/: extraction and segmentation prompts. Treat prompt edits as controlled experiments.
• tests/gold/: Gold Standard corpus and semantic specification for extraction behavior.
• scripts/: command-line support scripts such as Whisper cleanup and gold test execution.
• src/meeting_lab/normalization/: deterministic transcript cleanup.
• src/meeting_lab/chunking/: technical chunk creation; chunks are not topics.
• src/meeting_lab/segmentation/: experimental topic segmentation tooling.
• src/meeting_lab/extraction/: local LLM extraction flow and category extractor modules.
• src/meeting_lab/consolidation/: planned consolidation area.
• src/meeting_lab/protocol/: interim protocol rendering.
• src/meeting_lab/models/: current lightweight data models.
• samples/: sample inputs and generated/experimental artifacts; do not treat sample output as canonical source data.