Document project architecture and development methodology

- add AGENTS.md with development and prompt-engineering rules - add PROJECT_KNOWLEDGE.md summarizing current architecture and findings - add CHANGELOG.md - add ROADMAP.md - establish experiments.md as the project's experiment log - document Canonical Meeting Knowledge architecture - document Output Views and Knowledge Objects - capture accepted experimental results and engineering methodology
2026-07-31 08:25:16 +02:00
parent 5c03ed7efd
commit 09d125e54a
5 changed files with 1478 additions and 0 deletions
@@ -0,0 +1,124 @@
 # 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:
 ```text
 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.
@@ -0,0 +1,47 @@
 # Changelog
 ## Unreleased
 ### Added
 - Initial Meeting Lab project structure with source, docs, prompts, samples and
  tests directories.
 - Deterministic transcript normalization module.
 - Technical transcript chunking with block-aligned chunk generation.
 - Whisper JSON cleanup support.
 - Local Ollama-based chunk extraction flow.
 - Interim Markdown meeting protocol builder for technical validation.
 - Initial and windowed topic segmentation prototypes plus review tooling.
 - Gold Standard extraction corpus and gold-test runner.
 - Prompt loading support and common/decision prompt baseline.
 - Output-view architecture documentation for Canonical Meeting Knowledge,
  Working Protocol / Arbeitsprotokoll, Distribution Protocol /
  Verteilerprotokoll and Knowledge Objects / Wissensdatenbankeintrag.
 ### Changed
 - Refined the architecture from a single meeting protocol toward Canonical
  Meeting Knowledge as the planned semantic source of truth.
 - Clarified that Working Protocol, Distribution Protocol and Knowledge Objects
  are parallel renderings, not derived from one another.
 - Updated decision extraction semantics to include explicit process decisions
  and deferrals.
 - Simplified extraction prompt assembly around prompt files.
 ### Fixed
 - Fixed Whisper JSON chunk extraction to prefer `segments[*].text` over the
  aggregate top-level `text` field.
 - Added chunking tests to ensure chunks do not duplicate later blocks when no
  overlap is requested.
 - Added parser handling for model responses that contain thinking text before
  the final JSON object.
 ### Documentation
 - Added architecture, pipeline and data-model documentation.
 - Added output-view documentation.
 - Added Gold Standard prompt-engineering methodology.
 - Added formal decision-definition documentation.
 - Added scenario README files for the Gold Standard corpus.
@@ -0,0 +1,151 @@
 # Project Knowledge
 This is a compact operational summary of the current Meeting Lab state.
 ## Objective
 Meeting Lab develops and evaluates local methods for extracting structured
 organizational knowledge from real meeting recordings and transcripts. The
 project is a research and validation environment for a future Meeting
 Assistant, not a finished product.
 ## Implemented Pipeline Stages
 Implemented:
 - Whisper JSON cleanup via `scripts/clean_whisper_json.py`.
 - Transcript normalization in `src/meeting_lab/normalization/`.
 - Technical chunking in `src/meeting_lab/chunking/`.
 - Local per-chunk extraction in `src/meeting_lab/extraction/extract_chunks.py`.
 - Prompt loading from `src/meeting_lab/llm/prompts.py`.
 - Interim Markdown protocol generation in `src/meeting_lab/protocol/`.
 - Non-LLM unit tests for chunking, extraction helpers, protocol rendering and
  gold-test runner validation.
 Experimental/prototype:
 - Topic segmentation in `src/meeting_lab/segmentation/`.
 - Windowed segmentation and review output in `samples/chunks/`.
 - Gold Standard extraction corpus under `tests/gold/`.
 Planned:
 - Consolidation of extraction results.
 - Canonical Meeting Knowledge implementation as the semantic source of truth.
 - Final Working Protocol / Arbeitsprotokoll, Distribution Protocol /
  Verteilerprotokoll and Knowledge Objects / Wissensdatenbankeintrag renderers.
 ## Source Tree
 ```text
 src/meeting_lab/
  chunking/        technical transcript chunking
  consolidation/   planned merge/consolidation area
  extraction/      current local LLM extraction flow
  io/              lightweight file and JSON helpers
  llm/             Ollama and prompt support
  models/          current lightweight model definitions
  normalization/   deterministic transcript cleanup
  protocol/        interim Markdown protocol builder
  segmentation/    experimental topic segmentation tooling
 ```
 Supporting areas:
 - `docs/`: architecture, pipeline, data models and output-view concepts.
 - `prompts/`: active prompt files. Only `common.md` and `decisions.md` contain
  substantive extraction prompt text in the current tree.
 - `tests/gold/`: semantic gold tests and prompt-engineering methodology.
 - `samples/`: sample inputs and generated or experimental artifacts.
 - `scripts/`: operational scripts for cleanup and gold-test execution.
 ## Current Model Strategy
 The current extraction strategy is one normalized chunk per LLM call. This is
 preferred over expanding context windows or asking one model call to analyze a
 full meeting.
 Known working models from current project notes and experiment practice:
 - `qwen3:1.7b`: useful for smoke tests.
 - `qwen3.5:9b`: useful for meaningful extraction and segmentation work.
 LLM calls use Ollama locally. The current extractor defaults to `qwen3:8b`, but
 validated work may specify another model explicitly.
 ## Important Findings
 - Whisper JSON chunking must use `segments[*].text`, not only the top-level
  `text` field.
 - Independent chunk extraction is currently preferred.
 - Larger context windows can change classification behavior and increase
  instability.
 - Extraction and consolidation are separate problems.
 - Generation limits can truncate JSON.
 - Qwen thinking may be returned separately by the Ollama API.
 - Gold Standard tests are also a formal specification of meeting semantics.
 - Raw model responses should be preserved when diagnosing parser or truncation
  failures.
 ## Decision Taxonomy
 Accepted decision semantics:
 - A decision is an explicit agreement that creates a binding change in action,
  process, responsibility, approval status, timing or next step.
 - Included: substantive decisions, organizational decisions, process decisions,
  approvals, rejections, deferrals, explicit agreement not to decide yet, and
  explicit agreement to gather more information before deciding.
 - Excluded: opinions, preferences, proposals without agreement, open questions,
  current-state descriptions and explanations without commitment.
 - A process decision to defer a substantive decision is still a decision.
 - "No decision was reached" is different from "the group decided to defer the
  decision."
 Current Prompt Version 2 decision baseline:
 - `decision_simple`: passing.
 - `decision_deferred`: passing.
 - `decision_none`: passing.
 - Prompt Version 2 explicitly supports process decisions where the group agrees
  to defer a substantive decision until more information is available.
 ## Canonical Knowledge Architecture
 Canonical Meeting Knowledge is the planned semantic intermediate model and
 future single source of truth. It should preserve topics, facts, decisions,
 action items, open questions, positions, technical details, rationale,
 uncertainty, contradictions and source evidence.
 Output views are planned as independent renderings from that canonical model:
 - Working Protocol / Arbeitsprotokoll: relatively complete, optimized for
  recall and traceability.
 - Distribution Protocol / Verteilerprotokoll: concise and outcome-oriented,
  optimized for circulation.
 - Knowledge Objects / Wissensdatenbankeintrag: durable organizational knowledge
  optimized for reuse.
 The current `meeting_protocol.md` builder is an interim technical validation
 tool, not the final output-view architecture.
 ## Current Limitations
 - Discussion Blocks are documented as a stable semantic unit but are not yet a
  separate implemented pipeline artifact.
 - Topic segmentation exists as prototype tooling, not a stable pipeline stage.
 - Extraction is still a combined current flow, even though separate extractors
  are the intended architecture.
 - Consolidation is not implemented.
 - Canonical Meeting Knowledge is documented but not implemented.
 - Final output views are documented but not implemented.
 - Most prompt files are placeholders except the common and decision prompts.
 - Gold tests currently emphasize extraction semantics, especially decisions.
 ## Next Recommended Engineering Step
 Stabilize repeatable local extraction evaluation before broadening the pipeline:
 expand Gold Standard coverage by category, keep one-chunk extraction as the
 baseline, and use small prompt experiments with immediate non-regression checks.
 After extraction behavior is stable enough, implement consolidation with
 evidence retention as the next major pipeline stage.
@@ -0,0 +1,185 @@
 # Roadmap
 No dates are assigned. Phases describe dependency order, not release promises.
 ## Phase 1 - Stable Local Extraction
 Goal:
 - Establish reliable per-chunk extraction behavior for core meeting semantics.
 Deliverables:
 - Stronger Gold Standard coverage across facts, positions, decisions, todos,
  questions and technical details.
 - Improved category prompts.
 - Repeatable evaluation workflow.
 - Documented prompt experiment log.
 Prerequisites:
 - Existing chunk extraction flow.
 - Existing Gold Standard runner and methodology.
 Out of scope:
 - Full-transcript LLM extraction.
 - Larger context-window strategy changes without an explicit experiment.
 - Consolidation or final protocol rendering.
 ## Phase 2 - Consolidation
 Goal:
 - Merge independent extraction results into a coherent meeting-level
  representation without losing evidence.
 Deliverables:
 - Duplicate merging.
 - Evidence retention.
 - Category-shift reconciliation, especially facts versus positions and
  positions versus decisions.
 - Contradiction and uncertainty markers.
 - Consolidated meeting representation.
 Prerequisites:
 - Stable local extraction baseline.
 - Gold tests that expose cross-chunk duplication and category shifts.
 Out of scope:
 - Final Canonical Meeting Knowledge schema.
 - User-facing protocol polish.
 - Retrieval or RAG integration.
 ## Phase 3 - Canonical Meeting Knowledge
 Goal:
 - Define and implement the semantic intermediate model that becomes the source
  of truth for downstream outputs.
 Deliverables:
 - Canonical Meeting Knowledge schema.
 - Source evidence and traceability fields.
 - Clear distinction between durable knowledge and meeting-specific actions.
 - Migration path from consolidated extraction JSON into the canonical model.
 Prerequisites:
 - Consolidation behavior that preserves evidence and uncertainty.
 - Agreement on required semantic categories.
 Out of scope:
 - GUI.
 - Export formats beyond those needed to validate the model.
 - Knowledge-system storage design.
 ## Phase 4 - Output Views
 Goal:
 - Render purpose-specific outputs from Canonical Meeting Knowledge without
  changing meaning.
 Deliverables:
 - Working Protocol / Arbeitsprotokoll renderer.
 - Distribution Protocol / Verteilerprotokoll renderer.
 - Knowledge Objects / Wissensdatenbankeintrag renderer or structured export.
 - Tests or checks showing that output views are parallel renderings of the same
  canonical model.
 Prerequisites:
 - Implemented Canonical Meeting Knowledge.
 - Clear audience and completeness rules for each output view.
 Out of scope:
 - Additional analysis during rendering.
 - Deriving one output view from another.
 - Retrieval integration.
 ## Phase 5 - Review and Quality Control
 Goal:
 - Add optional review stages that improve omission detection, consistency and
  model selection.
 Deliverables:
 - Optional whole-transcript review.
 - Omission detection.
 - Consistency checks.
 - Model comparison workflow.
 - Hardware and runtime benchmarks.
 Prerequisites:
 - Stable extraction, consolidation and canonical model.
 - Representative test meetings.
 Out of scope:
 - Automatic acceptance of review suggestions without evidence.
 - Product UI work.
 - Cloud deployment.
 ## Phase 6 - Productization
 Goal:
 - Turn the validated pipeline into a usable local workflow.
 Deliverables:
 - Recording/transcription workflow.
 - FFmpeg integration.
 - Meeting metadata capture.
 - Participant entry.
 - GUI.
 - Stable deployment process.
 - Export workflows.
 Prerequisites:
 - Stable pipeline stages and output views.
 - Clear operational requirements for local use.
 Out of scope:
 - Enterprise knowledge retrieval.
 - Future Meeting Assistant integration beyond export contracts.
 - Cloud-first architecture.
 ## Phase 7 - Knowledge-System Integration
 Goal:
 - Reuse durable meeting knowledge in broader knowledge systems.
 Deliverables:
 - Structured Knowledge Objects.
 - Retrieval-ready storage format.
 - Future RAG integration path.
 - Reuse contracts for Meeting Assistant and other knowledge systems.
 Prerequisites:
 - Canonical Meeting Knowledge and Knowledge Objects are implemented and stable.
 - Durable knowledge is separated from meeting-specific actions and discussion
  history.
 Out of scope:
 - Building a full enterprise search product inside Meeting Lab.
 - Treating raw transcripts or generated protocols as the knowledge source of
  truth.
@@ -0,0 +1,971 @@
 # Experiments
 This file records durable technical experiments and findings for Meeting Lab.
 It is not a diary and does not replace commit history.
 ## Status values
 - Proposed: experiment idea exists, but no result is recorded.
 - Running: experiment is in progress and no decision has been made.
 - Accepted: finding is the current baseline or design conclusion.
 - Rejected: hypothesis was tested and should not be repeated as-is.
 - Superseded: finding was useful but has been replaced by a newer baseline.
 ## EXP-0001 - Whisper JSON interpretation
 Status: Accepted
 Date or period: 2026-07-29
 Hypothesis:
 Whisper JSON should be chunked from its segment stream, not from the aggregate
 top-level text field.
 Setup:
 `chunk_transcript.py` was updated to parse JSON input and prefer
 `segments[*].text` when `segments` exists. A regression test supplies JSON with
 both top-level `text` and separate segment texts.
 Inputs:
 - Minimal synthetic Whisper-style JSON in `tests/test_chunking.py`.
 - Real Whisper artifacts under `samples/whisper/`.
 Model / configuration:
 - No LLM.
 Result:
 The test verifies that the block stream is `["alpha", "beta", "gamma"]` and
 does not include the aggregate `"alpha beta gamma"` text. The repository history
 records this as the fix for the earlier failure where the first chunk contained
 the complete transcript.
 Decision:
 When `segments` exists, `segments[*].text` is the authoritative transcript
 stream. The top-level `text` field is only a fallback.
 Lessons learned:
 Whisper JSON is structured input. Treating it like plain text can duplicate the
 entire transcript and invalidate downstream chunking.
 Evidence:
 - `src/meeting_lab/chunking/chunk_transcript.py`
 - `tests/test_chunking.py`
 - Commit `4656523` - `Fix Whisper JSON chunk extraction`
 ## EXP-0002 - Technical transcript chunking baseline
 Status: Accepted
 Date or period: 2026-07-29 to 2026-07-30
 Hypothesis:
 Sequential technical chunks around the configured target size can preserve the
 transcript while keeping extraction calls small enough for local models.
 Setup:
 The chunker splits block-aligned text with configurable target, minimum,
 maximum and overlap settings. Tests verify no duplicate later blocks when
 overlap is zero. Generated meeting artifacts contain a nine-chunk manifest.
 Inputs:
 - Synthetic block list in `tests/test_chunking.py`.
 - `samples/whisper/meeting_speech_cleaned.json`.
 Model / configuration:
 - No LLM for chunking.
 - Manifest uses default chunking behavior recorded in
  `samples/whisper/meeting_speech_cleaned_chunks/manifest.json`.
 Result:
 With overlap set to zero, tests verify that all blocks appear exactly once. The
 real sample manifest contains nine chunks, mostly near the configured target
 size, with a smaller final chunk.
 Decision:
 Independent sequential chunks are the current technical baseline. One
 normalized chunk per extraction call is the preferred extraction strategy.
 Lessons learned:
 Chunking solves model-size constraints only. It must not perform topic
 detection or semantic merging.
 Evidence:
 - `src/meeting_lab/chunking/chunk_transcript.py`
 - `tests/test_chunking.py`
 - `samples/whisper/meeting_speech_cleaned_chunks/manifest.json`
 - `AGENTS.md`
 - `PROJECT_KNOWLEDGE.md`
 ## EXP-0003 - Conservative transcript normalization
 Status: Accepted
 Date or period: 2026-07-30
 Hypothesis:
 Transcript cleanup should improve readability without changing meeting
 semantics.
 Setup:
 The normalizer removes isolated filler sounds, immediate duplicate words or
 short duplicate phrases, and redundant whitespace. It records changed blocks in
 a JSON change log and explicitly preserves semantic content categories.
 Inputs:
 - Chunk text files under `samples/whisper/meeting_speech_cleaned_chunks/`.
 - Change logs such as `chunk_01_changes.json`.
 Model / configuration:
 - No LLM.
 Result:
 The implementation and generated change logs show a conservative policy:
 negations, qualifiers, dates, numbers, responsibilities, technical statements,
 deadlines, decisions and commitments are preserved.
 Decision:
 Normalization remains deterministic and low-risk. When uncertain, leave text
 unchanged.
 Lessons learned:
 Filler removal is useful only if it is tightly scoped. Broad cleanup can remove
 semantic cues needed by extraction.
 Evidence:
 - `src/meeting_lab/normalization/normalize_transcript.py`
 - `samples/whisper/meeting_speech_cleaned_chunks/chunk_01_changes.json`
 - `docs/pipeline.md`
 ## EXP-0004 - Full-context topic segmentation
 Status: Superseded
 Date or period: 2026-07-21 to 2026-07-22
 Hypothesis:
 A single full-context topic segmentation call can identify topic boundaries in
 a normalized transcript chunk.
 Setup:
 The initial segmentation prototype asked the model for topic changes and then
 converted those boundaries into continuous, non-overlapping segments.
 Inputs:
 - `samples/chunks/chunk_01_normalized.txt`.
 Model / configuration:
 - Generated artifact records `qwen3:14b`.
 Result:
 The generated artifact contains 85 blocks, three topic-change boundaries and
 four segments. The run metadata records a substantially longer elapsed time
 than the later windowed artifact for the same input.
 Decision:
 Full-context segmentation was useful as a prototype, but it was superseded by
 windowed segmentation and manual review tooling.
 Lessons learned:
 The prototype established the boundary-to-segment representation, but did not
 settle segmentation quality.
 Evidence:
 - `src/meeting_lab/segmentation/segment_topics.py`
 - `samples/chunks/chunk_01_normalized_segments.json`
 - Commit `f234efc` - `Add initial topic segmentation prototype`
 - Commit `889a4fe` - `Detect topic boundaries as continuous segments`
 ## EXP-0005 - Windowed topic segmentation and review
 Status: Accepted
 Date or period: 2026-07-22
 Hypothesis:
 Windowed topic segmentation can reduce runtime and make boundary evaluation
 more inspectable than a single full-context call.
 Setup:
 `segment_topics_windowed.py` analyzes overlapping windows and reports only
 boundaries from the decision range. Python merges boundaries into continuous,
 non-overlapping segments. `review_segmentation.py` renders each boundary with
 neighboring transcript context for manual classification.
 Inputs:
 - `samples/chunks/chunk_01_normalized.txt`.
 - Full meeting normalized chunks under
  `samples/whisper/meeting_speech_cleaned_chunks/`.
 Model / configuration:
 - `samples/chunks` artifact: `qwen3:8b`, window size 20, overlap 3.
 - Full-meeting chunk artifacts: `qwen3.5:9b`, window size 20, overlap 3.
 Result:
 The `samples/chunks` windowed artifact produced 11 boundaries and 12 segments
 for 85 blocks, with recorded elapsed time lower than the full-context artifact.
 Manual review output shows that some boundaries were assessed as subtopics
 rather than full topic changes. Full-meeting artifacts show one window per
 already-small normalized chunk and two segments per chunk.
 Decision:
 Windowed segmentation and review tooling are accepted as prototype tooling, not
 as a stable production segmentation stage.
 Lessons learned:
 Windowing improves inspectability and can reduce runtime, but it can also
 cluster boundaries and over-segment. Manual review remains necessary.
 Evidence:
 - `src/meeting_lab/segmentation/segment_topics_windowed.py`
 - `src/meeting_lab/segmentation/review_segmentation.py`
 - `samples/chunks/chunk_01_normalized_windowed_segments.json`
 - `samples/chunks/chunk_01_normalized_windowed_segments_review.md`
 - `samples/whisper/meeting_speech_cleaned_chunks/*_windowed_segments.json`
 - Commit `1a6d731` - `Add windowed segmentation pipeline and review tooling`
 ## EXP-0006 - Qwen model comparison
 Status: Accepted
 Hypothesis:
 Larger local Qwen-family models should improve meaningful extraction and
 segmentation, but model size alone will not solve prompt or pipeline problems.
 Setup:
 Project work used smaller models for smoke checks and larger local models for
 meaningful extraction or segmentation. Artifacts and project knowledge record
 the currently useful model roles.
 Inputs:
 - Gold Standard scenarios under `tests/gold/`.
 - Generated segmentation artifacts under `samples/`.
 - Generated extraction artifacts under
  `samples/whisper/meeting_speech_cleaned_chunks/`.
 Model / configuration:
 - `qwen3:1.7b`: smoke-test model according to project knowledge.
 - `qwen3.5:9b`: current meaningful extraction and segmentation model according
  to project knowledge and generated full-meeting segmentation artifacts.
 - `qwen3:8b` and `qwen3:14b`: present in earlier segmentation artifacts.
 Result:
 The repository supports the conclusion that `qwen3.5:9b` is the meaningful
 current experiment model and `qwen3:1.7b` is useful for smoke tests. Larger
 models and longer contexts may increase runtime substantially, but no hardware
 benchmark suite is recorded.
 Decision:
 Use `qwen3:1.7b` for smoke tests and `qwen3.5:9b` for meaningful current
 experiments. Do not assume model size alone fixes prompt or pipeline design.
 Lessons learned:
 Evaluation must separate model capability from prompt clarity, context
 strategy, extraction schema and consolidation.
 Evidence:
 - `PROJECT_KNOWLEDGE.md`
 - `samples/whisper/meeting_speech_cleaned_chunks/*_windowed_segments.json`
 - `samples/chunks/chunk_01_normalized_segments.json`
 - `samples/chunks/chunk_01_normalized_windowed_segments.json`
 ## EXP-0007 - Thinking output and Ollama API behavior
 Status: Accepted
 Date or period: 2026-07-30
 Hypothesis:
 Thinking-capable Qwen models may return reasoning separately from the final
 answer, and extraction parsing should not fail merely because extra text or
 multiple JSON objects appear.
 Setup:
 The Ollama response reader checks `response`, chat-style `message.content` and
 then `thinking`. The JSON parser tries a full parse first, then scans JSON
 object candidates and returns the final valid object. A regression test covers
 thinking text before final JSON.
 Inputs:
 - Synthetic parser test in `tests/test_extraction_protocol.py`.
 Model / configuration:
 - No LLM run in the test.
 - Code path is used by Ollama extraction.
 Result:
 The parser can handle additional text and multiple JSON objects where the final
 valid object is the intended answer. Current code still falls back to `thinking`
 only if no usable response or message content is present.
 Decision:
 Keep parser robustness, but do not treat thinking output as the root cause of
 all extraction failures.
 Lessons learned:
 API response shape and model output shape are separate concerns. Preserve raw
 responses when diagnosing failures.
 Evidence:
 - `src/meeting_lab/extraction/extract_chunks.py`
 - `tests/test_extraction_protocol.py`
 - `PROJECT_KNOWLEDGE.md`
 ## EXP-0008 - JSON truncation and generation limits
 Status: Accepted
 Hypothesis:
 Some extraction failures are caused by generation limits truncating JSON rather
 than by prompt wording or parser behavior.
 Setup:
 A `qwen3.5:9b` extraction failure was diagnosed as truncated JSON. The
 generation limit was increased for the successful path. Exact failing limit is
 not recorded in the repository; the current extractor default is verifiably
 `--num-predict 8192`.
 Inputs:
 - Local extraction runs referenced by project knowledge.
 - Current extraction CLI.
 Model / configuration:
 - `qwen3.5:9b`.
 - Current extractor default: `num_predict=8192`.
 Result:
 Increasing the generation limit fixed the technical JSON failure. This was not
 primarily a parser or prompt problem.
 Decision:
 When JSON is truncated, inspect raw output and generation limits before editing
 prompts.
 Lessons learned:
 Invalid JSON can be a runtime-budget symptom. Prompt changes are the wrong
 first response if the model simply ran out of output tokens.
 Evidence:
 - `src/meeting_lab/extraction/extract_chunks.py`
 - `PROJECT_KNOWLEDGE.md`
 - `AGENTS.md`
 ## EXP-0009 - Minimal end-to-end pipeline
 Status: Accepted
 Date or period: 2026-07-30
 Hypothesis:
 A minimal local pipeline can transform Whisper output into chunk extractions
 and an interim protocol, proving the technical path before the final
 architecture exists.
 Setup:
 The repository added cleanup, normalization, chunking, extraction and protocol
 builder scripts, with sample generated artifacts.
 Inputs:
 - `samples/whisper/meeting_speech.json`
 - `samples/whisper/meeting_speech_cleaned.json`
 - Generated chunks and normalized chunks under
  `samples/whisper/meeting_speech_cleaned_chunks/`.
 Model / configuration:
 - Local Ollama extraction for chunk JSON.
 - Windowed segmentation artifacts use `qwen3.5:9b`.
 Result:
 The repository contains cleaned input, nine chunks, nine normalized chunks, nine
 extraction JSON files, windowed segmentation artifacts and
 `meeting_protocol.md`.
 Decision:
 The minimal pipeline is technically validated. The first protocol builder is an
 interim validation tool, not the final architecture.
 Lessons learned:
 End-to-end execution exposed the next limitation: extraction output needs
 consolidation and purpose-specific rendering.
 Evidence:
 - `scripts/clean_whisper_json.py`
 - `src/meeting_lab/normalization/normalize_transcript.py`
 - `src/meeting_lab/chunking/chunk_transcript.py`
 - `src/meeting_lab/extraction/extract_chunks.py`
 - `src/meeting_lab/protocol/build_protocol.py`
 - `samples/whisper/meeting_speech_cleaned_chunks/`
 - Commit `07b0d80` - `Implement first end-to-end meeting analysis pipeline`
 ## EXP-0010 - Gold Standard corpus
 Status: Accepted
 Date or period: 2026-07-30
 Hypothesis:
 Reproducible prompt engineering requires synthetic transcripts with explicit
 expected semantic outputs.
 Setup:
 The Gold Standard corpus defines scenario directories with `transcript.txt`,
 `expected.json` and README files describing ground truth and common model
 mistakes. The runner validates schema keys and writes `actual.json` for a
 scenario.
 Inputs:
 - Gold scenarios under `tests/gold/`.
 Model / configuration:
 - Runner requires an explicit Ollama model for LLM evaluation.
 - Existing unit tests for the runner do not invoke Ollama.
 Result:
 The corpus gives stable semantics for decisions, facts, positions, todos,
 questions, technical details and difficult mixed cases. Initial structured
 transcripts are Phase 1 and easier than raw Whisper-style transcripts.
 Decision:
 Use Gold Standard tests as both regression tests and formal meeting-semantics
 specification. Raw or unlabelled transcript cases remain later-phase work.
 Lessons learned:
 Without expected outputs, prompt changes cannot be evaluated reproducibly.
 Evidence:
 - `tests/gold/`
 - `scripts/run_gold_test.py`
 - `tests/test_gold_runner.py`
 - Commit `f7ad9ba` - `Establish prompt engineering baseline with Gold Standard tests`
 ## EXP-0011 - Gold-test quality and unique ground truth
 Status: Accepted
 Date or period: 2026-07-30
 Hypothesis:
 If a prompt produces unexpected behavior, the gold test itself may be ambiguous
 and should be reviewed before the prompt is changed.
 Setup:
 Decision-focused scenarios were clarified during baseline creation. The current
 methodology requires checking unique ground truth before changing prompts.
 Inputs:
 - `decision_simple`
 - `decision_deferred`
 - `decision_none`
 - Gold methodology document.
 Model / configuration:
 - Prompt Version 2 baseline work.
 Result:
 `decision_simple` required clarification around the explicit agreement and
 nearby non-decision wording. The earlier negative/deferral ambiguity is now
 represented by distinct `decision_none` and `decision_deferred` scenarios in
 the repository. Punctuation is not reliable evidence for Whisper transcripts;
 agreement language and wording must carry the semantics.
 Decision:
 Ambiguous gold tests must be reviewed before prompt changes. Do not treat
 punctuation as reliable evidence in real Whisper-style transcripts.
 Lessons learned:
 Bad gold tests create false prompt failures and can encourage overfitting.
 Evidence:
 - `tests/gold/PROMPT_ENGINEERING_METHODOLOGY.md`
 - `tests/gold/decision_simple/README.md`
 - `tests/gold/decision_deferred/README.md`
 - `tests/gold/decision_none/README.md`
 - Commit `f7ad9ba`
 ## EXP-0012 - Decision taxonomy
 Status: Accepted
 Date or period: 2026-07-30
 Hypothesis:
 Decision extraction needs a formal taxonomy that distinguishes substantive
 decisions from process decisions and non-decisions.
 Setup:
 The decision definition document and decision prompt define included and
 excluded categories. Gold tests cover explicit decisions, true no-decision
 cases and deferrals.
 Inputs:
 - `tests/gold/DECISION_DEFINITION.md`
 - `prompts/decisions.md`
 - Decision gold scenarios.
 Model / configuration:
 - Prompt Version 2 baseline.
 Result:
 Accepted decision categories include substantive decisions, organizational
 decisions, process decisions, approvals, rejections, deferrals, explicit
 decisions not to decide yet and explicit agreement to gather more information
 before deciding. Opinions, preferences and proposals without agreement are not
 decisions.
 Decision:
 "No decision was reached" and "the decision was deferred" are distinct semantic
 outcomes.
 Lessons learned:
 Deferral can be a valid process decision even when the substantive topic remains
 unresolved.
 Evidence:
 - `tests/gold/DECISION_DEFINITION.md`
 - `tests/gold/decision_deferred/`
 - `tests/gold/decision_none/`
 - `prompts/decisions.md`
 ## EXP-0013 - Prompt engineering methodology
 Status: Accepted
 Date or period: 2026-07-30
 Hypothesis:
 Prompt iteration needs strict experimental controls to prevent regression,
 overfitting and arbitrary prompt churn.
 Setup:
 The methodology was documented alongside the Gold Standard corpus and later
 summarized for agents.
 Inputs:
 - Gold scenarios.
 - Prompt files.
 Model / configuration:
 - Applies to all prompt experiments.
 Result:
 The accepted method is one prompt change per iteration, one target test at a
 time, immediate validation, no regressions, no `expected.json` edits merely to
 force a pass, no test-specific prompt hacks, stopping after two consecutive
 non-improving iterations, and verifying unique ground truth before prompt
 changes.
 Decision:
 Prompt changes are controlled experiments. See `AGENTS.md` for agent operating
 rules.
 Lessons learned:
 Most prompt changes are not isolated unless the experiment explicitly constrains
 the target and regression set.
 Evidence:
 - `tests/gold/PROMPT_ENGINEERING_METHODOLOGY.md`
 - `AGENTS.md`
 - Commit `f7ad9ba`
 ## EXP-0014 - Decision Prompt Version 2
 Status: Accepted
 Date or period: 2026-07-30
 Hypothesis:
 Adding explicit process-decision language to the decision prompt can preserve
 true decision detection while recognizing deferrals.
 Setup:
 Prompt Version 2 added explicit support for deferrals and process decisions.
 The baseline was validated on three decision scenarios.
 Inputs:
 - `decision_simple`
 - `decision_deferred`
 - `decision_none`
 Model / configuration:
 - Prompt Version 2.
 - Model used for validation is not recorded in the committed methodology.
 Result:
 The committed methodology records all three baseline scenarios as passing. The
 current generated `actual.json` files also show the expected decision count for
 these decision scenarios, although some non-decision categories remain less
 complete.
 Decision:
 Prompt Version 2 is the current decision baseline. Explicit deferrals are
 recognized as process decisions.
 Lessons learned:
 Decision-count success does not imply all categories are solved. Category-level
 evaluation must continue.
 Evidence:
 - `tests/gold/PROMPT_ENGINEERING_METHODOLOGY.md`
 - `tests/gold/decision_simple/actual.json`
 - `tests/gold/decision_deferred/actual.json`
 - `tests/gold/decision_none/actual.json`
 - `prompts/decisions.md`
 ## EXP-0015 - Difficult synthetic meeting
 Status: Running
 Date or period: 2026-07-30
 Hypothesis:
 A deliberately adversarial synthetic meeting can expose extraction failures
 that simple category tests miss.
 Setup:
 `evil_meeting` includes interruptions, corrections, absent referenced people,
 near-decisions, changed positions and one expected explicit decision.
 Inputs:
 - `tests/gold/evil_meeting/`.
 Model / configuration:
 - Existing generated `actual.json`; exact model is not stored in the artifact.
 Result:
 The generated result found the expected FR-7 exclusion decision. It also
 classified "do not migrate until the mapping table is checked" as an additional
 decision. The current expected file treats that statement as a position, but
 contextual review suggests it may be a valid process instruction or decision.
 Decision:
 Do not classify this as a simple model failure without reviewing the gold
 standard. The scenario exposes a semantic gap in the expected output.
 Lessons learned:
 Difficult synthetic cases are valuable because they reveal ambiguity in the
 specification as well as model mistakes.
 Evidence:
 - `tests/gold/evil_meeting/README.md`
 - `tests/gold/evil_meeting/expected.json`
 - `tests/gold/evil_meeting/actual.json`
 - See EXP-0011 and EXP-0012.
 ## EXP-0016 - Context-size extraction comparisons
 Status: Rejected
 Hypothesis:
 Increasing extraction context from one chunk to neighboring chunk groups should
 make extraction more complete and therefore should become the baseline.
 Setup:
 Comparisons were made across one chunk and grouped contexts: 1+2, 2 only, 2+3
 and 1+2+3.
 Inputs:
 - Normalized meeting chunks.
 Model / configuration:
 - Current project knowledge identifies `qwen3.5:9b` as the meaningful model for
  extraction experiments.
 Result:
 More context sometimes improved completeness, but it also shifted category
 classification, added duplicates and reduced stability. No numeric winner is
 recorded in the repository.
 Decision:
 Do not adopt larger extraction windows as the baseline. Independent chunk
 extraction remains current strategy. Recover global context through
 consolidation rather than continuously enlarging extraction windows.
 Lessons learned:
 Context size is not a monotonic quality knob. It changes the task the model is
 performing.
 Evidence:
 - `PROJECT_KNOWLEDGE.md`
 - `AGENTS.md`
 - `ROADMAP.md`
 - See EXP-0002 and EXP-0018.
 ## EXP-0017 - Independent full-meeting chunk extraction
 Status: Accepted
 Hypothesis:
 Extracting every normalized chunk independently can produce enough structured
 material for a useful protocol draft.
 Setup:
 Nine normalized chunks were extracted into separate JSON files and then
 rendered by the interim protocol builder.
 Inputs:
 - `samples/whisper/meeting_speech_cleaned_chunks/chunk_01_normalized.txt`
  through `chunk_09_normalized.txt`.
 Model / configuration:
 - Existing extraction artifacts do not record model metadata.
 Result:
 The nine extraction files contain facts, decisions, todos, questions and
 technical details. `meeting_protocol.md` aggregates them into a readable draft.
 Duplicates, category shifts and synthesis became the dominant limitations.
 Decision:
 Independent chunk extraction is useful enough to keep as the baseline, but it
 requires a consolidation stage.
 Lessons learned:
 Per-chunk extraction gives recall-oriented raw material. It does not by itself
 produce a polished or canonical meeting representation.
 Evidence:
 - `samples/whisper/meeting_speech_cleaned_chunks/chunk_*_extraction.json`
 - `samples/whisper/meeting_speech_cleaned_chunks/meeting_protocol.md`
 - `src/meeting_lab/protocol/build_protocol.py`
 - See EXP-0018.
 ## EXP-0018 - Human protocol comparison and output-view split
 Status: Accepted
 Date or period: 2026-07-30
 Hypothesis:
 One generated protocol cannot satisfy every use case; protocol output should be
 separated by purpose and audience.
 Setup:
 The interim machine protocol was compared against the desired human protocol
 shape and then the architecture was revised toward parallel output views.
 Inputs:
 - Interim `meeting_protocol.md`.
 - Architecture and output-view documentation.
 Model / configuration:
 - Not applicable; this is a design evaluation.
 Result:
 The human protocol target is denser and organized by purpose and topic rather
 than extraction categories. The machine extraction retains more context and is
 useful for recall, but it is not the right direct source for a concise
 distribution artifact or durable knowledge entry.
 Decision:
 Separate final outputs into Working Protocol / Arbeitsprotokoll, Distribution
 Protocol / Verteilerprotokoll and Knowledge Objects /
 Wissensdatenbankeintrag.
 Lessons learned:
 Rendering is a separate concern from extraction and consolidation. Output views
 must be parallel renderings of shared semantics, not transformations of one
 another.
 Evidence:
 - `samples/whisper/meeting_speech_cleaned_chunks/meeting_protocol.md`
 - `docs/output-views.md`
 - `docs/architecture.md`
 - `docs/pipeline.md`
 - Commit `5c03ed7` - `Refine canonical meeting knowledge architecture`
 ## EXP-0019 - Consolidation and Canonical Meeting Knowledge
 Status: Accepted
 Date or period: 2026-07-30
 Hypothesis:
 Extraction, consolidation and output rendering are separate problems and should
 not be collapsed into one LLM prompt or one protocol file.
 Setup:
 The architecture was refined after the minimal pipeline and protocol draft
 showed duplicate, synthesis and audience-specific rendering limitations.
 Inputs:
 - Extraction JSON artifacts.
 - Interim protocol draft.
 - Architecture and data-model documentation.
 Model / configuration:
 - Not applicable; this is an architectural conclusion.
 Result:
 The accepted design is a planned Canonical Meeting Knowledge layer as the
 semantic source of truth, with Working Protocol, Distribution Protocol and
 Knowledge Objects as parallel output views. Consolidation must merge duplicates,
 preserve evidence, reconcile category shifts and mark contradictions or
 uncertainty.
 Decision:
 Consolidation is the next major engineering step after stable local extraction.
 Canonical Meeting Knowledge and final output views are planned, not implemented.
 Lessons learned:
 Global meeting understanding should be recovered by consolidation over
 evidence-bearing extractions, not by silently changing output views or expanding
 LLM context indefinitely.
 Evidence:
 - `docs/architecture.md`
 - `docs/pipeline.md`
 - `docs/data-models.md`
 - `docs/output-views.md`
 - `PROJECT_KNOWLEDGE.md`
 - `ROADMAP.md`
 - Commit `5c03ed7`