kc-beta 0.7.5 → 0.8.3

package/template/skills/en/corner-case-management/SKILL.md

@@ -1,22 +1,35 @@
 ---
 name: corner-case-management
 tier: meta
-description: Identify, catalog, and handle corner cases that do not fit the mainstream verification workflow. Use when the evolution loop classifies a failure as a corner case (affecting less than ~10% of documents), when adding a new edge case to the registry, or when deciding whether a corner case should be promoted to a systemic fix. Also use when designing the corner case detection mechanism for a workflow.
+description: Identify, catalog, and handle corner cases that do not fit the mainstream verification workflow. Use AFTER several rounds of skill/workflow iteration have surfaced documents that genuinely don't fit and can't be accommodated by reasonable changes to the standard flow. Covers when something is a corner case vs. a systemic fix needed, how to register it, how to wire detection-and-resolve so the corner case stays out of the hot path until a similar document appears again, and when to promote a corner case to a regular rule.
 ---
 
 # Corner Case Management
 
-A good workflow handles 90% of cases cleanly. Corner cases are the other 10%. They are individually rare but collectively significant. The key insight: do NOT patch the main workflow to handle them. That leads to spaghetti logic, fragile code, and regressions.
+A good workflow handles the bulk of cases cleanly. Corner cases are documents that don't fit — individually rare, collectively non-negligible. The key insight: do NOT patch the main workflow to handle them. That leads to spaghetti logic, fragile code, and regressions.
 
-Instead, maintain a separate registry. Check incoming documents against the registry before the standard workflow. Handle matches with specific resolutions.
+Instead, maintain a separate registry. Check incoming documents against the registry; handle matches with specific resolutions; keep the main workflow lean.
+
+## When to reach for this skill
+
+Corner cases are identified **after** the testing iterations, not during initial design. The typical pathway:
+
+1. You've built a skill/workflow for a rule.
+2. You've run it on the sample set. Most cases pass; some fail.
+3. You iterate — change code, change prompts, run back-tests.
+4. After several rounds, some cases stubbornly don't fit. Either:
+ - The current workflow doesn't catch them and changing the workflow to catch them would cost too much (breaks unrelated cases, adds too much complexity, requires architectural rework).
+ - The cases are swinging — one round of changes fits them, the next round breaks them, and oscillation continues.
+
+That's when you use this skill. Not on the first iteration. Not when you can plausibly fix it in the workflow. Only when fitting the case into the standard flow costs more than the case is worth.
 
 ## Philosophy
 
-Corner cases are a fact of life in document verification. Financial documents are produced by thousands of different organizations, each with their own formatting quirks, templates, and interpretations of regulations. No workflow will handle every variant.
+Corner cases are a fact of life in document verification. Financial documents come from thousands of different organizations, each with their own formatting quirks, templates, and interpretations of regulations. No workflow will handle every variant.
 
-The question is not "how do I eliminate corner cases?" but "how do I manage them efficiently?"
+The question is not "how do I eliminate corner cases?" but "how do I manage them efficiently without polluting the main path?"
 
-The answer is: separate them from the main logic. Keep the workflow clean. Keep the corner cases cataloged, detectable, and resolvable.
+The answer is: separate them. Keep the main workflow clean. Keep the corner cases cataloged, detectable, and resolvable when they recur.
 
 ## The Corner Case Registry
 
@@ -39,7 +52,7 @@ A structured file (`corner_cases.json`) in the rule skill's `assets/` directory:
       "action": "Multiply extracted value by 100 before threshold comparison",
       "code_snippet": "if value < 1.0: value *= 100"
     },
-    "discovered_at": "2026-04-01",
+    "discovered_at": "<date>",
     "iteration": 3,
     "status": "active"
   }
@@ -53,60 +66,67 @@ Each entry captures:
 - **When** it was discovered and in which iteration.
 - **Status**: active, promoted (moved to main workflow), or deprecated.
 
-## Detection During Execution
+## How to handle corner cases — lazy retrieval with a high bar
+
+Corner cases live in the registry, not in the main verification path. They're **lazily loaded** with a **high retrieval threshold**, meaning:
 
-Before running the standard workflow on a document:
+- The main workflow runs first on every document.
+- The registry is consulted only when a new incoming document resembles a previously-collected corner case strongly enough to trigger that entry.
+- The "strongly enough" bar should be set high — false matches drag in a wrong resolution and pollute the main result. Better to miss a match (the main workflow handles it, possibly imperfectly) than to apply an irrelevant corner-case patch.
 
-1. Load the corner case registry for the relevant rule.
-2. Check the document against each active corner case's detection pattern.
-3. If a match exceeds the confidence threshold, apply the specific resolution instead of (or in addition to) the standard workflow.
-4. Log that a corner case was triggered.
+Two detection patterns work for this:
 
-This is similar to a RAG pipeline with progressive disclosure:
-- The registry is the knowledge base.
-- Detection patterns are the retrieval queries.
-- High confidence thresholds prevent false matches.
-- Only relevant corner cases are loaded into context.
+- **Cheap deterministic match**: regex or keyword fingerprint over document text. Fast, run on every document.
+- **Embedding-based similarity**: compute embedding of the document's rule-relevant region, compare to embeddings of registered corner cases. Catches semantic resemblance the regex misses; costs more.
 
-## When to Add a Corner Case
+For early-stage rules with a small registry, deterministic detection is enough. For mature rules with dozens of registered cases, embedding-based similarity scales better.
+
+When a match fires:
+1. Log that the corner case was triggered (audit visibility).
+2. Apply the registered resolution.
+3. Skip / supplement / override the standard workflow as the resolution prescribes.
+
+## When to add a corner case
 
 Add a corner case when:
-- The evolution loop classifies a failure as non-systemic (affects <10% of documents).
-- The failure has a recognizable, describable pattern.
-- The resolution is clear and self-contained.
+- Iterations of the standard workflow can't accommodate the document without disproportionate cost.
+- The failure has a recognizable, describable pattern (a fingerprint to detect again).
+- The resolution is clear and self-contained (not "rewrite the workflow").
 
 Do NOT add a corner case when:
-- The failure affects many documents (that is a systemic issue — fix the workflow).
-- The failure has no discernible pattern (that may be a data quality issue — escalate to developer user).
-- The resolution would require changing the core judgment logic (that belongs in the main workflow).
+- The failure affects many documents — that's not a corner case, it's a pattern, and the main workflow should change.
+- The failure has no discernible pattern — that may be a data quality issue; escalate to the developer user.
+- The resolution would require changing the core judgment logic — that belongs in the main workflow.
 
-## When to Promote a Corner Case
+## When to promote a corner case
 
 A corner case should be promoted to the main workflow (i.e., the resolution becomes part of the standard logic) when:
-- It starts appearing in >10% of documents. It is no longer a corner case — it is a pattern.
+- It starts appearing across many documents. It's no longer a corner case — it's a pattern.
 - Multiple similar corner cases suggest a common underlying issue.
 - The developer user explicitly says "this is how it always works."
 
 When promoting, remove the corner case from the registry and update the workflow. Version both changes.
 
-## Human Visibility
+## Human visibility
 
 The corner case registry must be readable and manageable by the developer user:
+
 - Format it clearly (JSON or a markdown table).
-- Include enough context that a domain expert can understand each case without reading the code.
+- Include enough context that a domain expert can understand each case without reading code.
 - Report new corner cases in the dashboard.
 - Allow the developer user to add corner cases from their own expertise.
 
-Developer users often know about edge cases that the coding agent has not yet encountered. They should be able to add entries like:
+Developer users often know about edge cases that the agent has not yet encountered. They should be able to add entries like:
 - "Bank XYZ always uses a different template for their Q4 reports."
 - "Mutual fund documents from before 2020 follow the old regulation format."
 
 These are valuable inputs that prevent future failures.
 
-## Corner Case Cost
+## Corner case cost
 
 Every corner case has a runtime cost: the detection check runs on every document. Keep the registry lean:
+
 - Remove deprecated corner cases.
 - Merge similar corner cases into a single entry with a broader pattern.
-- Keep detection patterns efficient (prefer regex over LLM-based detection).
-- Monitor the registry size. If it grows beyond ~50 entries for a single rule, that suggests the workflow itself needs improvement.
+- Keep detection patterns efficient (prefer regex over LLM-based detection where possible).
+- Monitor the registry size. When it grows large for a single rule, that's a signal the workflow itself needs improvement — many of those "corner" cases probably want promotion to mainline handling.

package/template/skills/en/cross-document-verification/SKILL.md

@@ -1,132 +1,137 @@
 ---
 name: cross-document-verification
 tier: meta
-description: Perform case-level analysis across multiple documents for the same transaction. Use when documents do not exist in isolation — main contracts have appendices, loan applications come bundled with income certificates, bank statements, credit reports, and property appraisals. Use to build comparison matrices, detect contradictions (hard mismatches and soft implausibilities), classify severity, and flag fraud signals. Also use when user or end-user reports a cross-document inconsistency — these reports are ground truth and take priority over agent judgment.
+description: Build cross-document verification rule-skills and workflows — i.e., rules where the verdict depends on facts that appear in MORE than one document. Use when authoring or distilling a rule that requires comparing entities/values across documents in a case (main contract + appendices, loan application + income certificate + bank statement, etc.). Covers what the rule definition must specify (source-doc → entity → target-doc → entity → consistency level), how the resulting check.py/workflow walks the case, contradiction types to handle, and severity classification. Distinct from `compliance-judgment` (within-doc rules); KC is the builder, not the executor.
 ---
 
-# Cross-Document Verification
+# Cross-Document Verification — Building Rules That Span Documents
 
-Single-document verification asks: does this document comply with the rules? Cross-document verification asks a different question: do all the documents in this transaction tell a consistent story?
+KC's job in this phase is **building** verification rules that span multiple documents — not executing cross-doc checks at runtime. The output is a rule-skill / workflow that, once shipped, can be applied by KC or downstream systems to any case.
 
-This is the difference between a document checker and a case analyst. A document checker reviews files one at a time. A case analyst lays them all on the table and looks for the threads that connect — or contradict — each other. When you activate cross-document verification, you are upgrading the system from checker to analyst.
+If a rule's verdict depends on facts in more than one document, that fact has to be encoded in the rule itself. You can't build a within-doc check.py and hope the cross-doc check happens by magic at production time.
 
-## The Case Concept
+## What the rule definition must specify
 
-A case is the set of documents that belong to one transaction, one borrower, or one deal. Documents within a case share entities: names, dates, amounts, identifiers. These shared entities are your anchors for comparison.
+For a cross-doc rule, the catalog entry needs more than just "description + falsifiability_statement". It needs an **explicit cross-doc trajectory**:
 
-Two common case patterns:
+1. **Starting document class**: which document do we start from? How do we classify a document as belonging to this class? (e.g., "loan application form", "main contract", "annual disclosure report")
+2. **Anchor entity in the starting doc**: what do we extract first? (e.g., applicant ID, borrower name, contract reference number, reported total amount)
+3. **Target document class(es)**: which document(s) must we cross-check against? How do we identify them within the same case? (shared anchor key, naming pattern, explicit reference in the starting doc)
+4. **Target entity in each target doc**: what do we extract from each target doc to compare? It may or may not have the same field name — "monthly income" on the application vs. "average deposit" on the bank statement.
+5. **Consistency level for PASS**: when do we say the documents agree? Exact equality? Equality within tolerance? Plausibility check (within 1.5× of the other value)? Reciprocal-reference present?
+6. **What FAIL looks like**: hard mismatch, soft contradiction, or missing reciprocal reference — and what severity each carries.
 
-1. **Main contract + appendices/supplements.** Same issuer, formally cross-referenced. The main contract states the total, the appendices break it down. The main contract references Appendix B; Appendix B must exist and match. The team has extensive experience with inconsistencies in this pattern — totals that do not match line item sums, referenced appendices that are missing or outdated, version mismatches between main body and supplements.
+Without these five anchors, the rule is just a wish. With them, the resulting check.py can walk the case deterministically.
 
-2. **Multi-source bundle.** Loan application + income certificate + bank statement + credit report + property appraisal. Different issuers, different formats, same borrower. The applicant's name, ID number, income, and employment must be consistent across all documents.
+## How this differs from `compliance-judgment`
 
-In both patterns, the shared entities are the anchors. Every anchor that appears in more than one document is a candidate for cross-verification.
+`compliance-judgment` covers within-doc rules: read one document, apply the rule, return a verdict. The judgment can be regex, deterministic Python, or LLM-augmented — but the input is one document.
 
-## Building the Comparison Matrix
+This skill covers rules where the **input is a case** (a set of related documents). The check.py for such a rule:
 
-The comparison matrix is the core artifact. Rows are shared fields. Columns are source documents. Each cell contains the value found in that document for that field, or is marked absent.
+- Receives a case-level structure (list of documents + metadata), not a single doc.
+- Performs entity extraction across the relevant documents.
+- Builds the comparison matrix needed for that specific rule (not a generic everything-vs-everything matrix — only the fields this rule cares about).
+- Applies the consistency check defined in the rule.
+- Returns the verdict plus the matrix-cells that drove it (evidence).
 
-Example matrix for a loan case:
+KC is the **builder** of this check.py / workflow, not the executor. The teaching below is about what to design, not what to do at runtime.
 
-| Field | Application | Income Cert | Bank Statement | Credit Report |
-|-------|-------------|-------------|----------------|---------------|
-| Applicant name | Zhang Wei | Zhang Wei | Zhang Wei | Zhang W. |
-| ID number | 310...1234 | 310...1234 | — | 310...1234 |
-| Monthly income | 85,000 | 82,000 | avg 43,000 | — |
-| Employer | ABC Corp | ABC Corp Ltd | — | ABC Corporation |
-| Employment start | 2019-03 | 2019-06 | — | 2019 |
+## Case patterns to design for
 
-Example matrix for a contract + appendices case:
+Two patterns cover most cross-doc rules:
 
-| Field | Main Contract | Appendix A | Appendix B |
-|-------|---------------|------------|------------|
-| Total amount | 5,000,000 | — | 4,850,000 (sum of items) |
-| Party B name | Shenzhen XX Co. | Shenzhen XX Co., Ltd | Shenzhen XX Co. |
-| Effective date | 2024-01-15 | 2024-01-15 | 2024-02-01 |
+1. **Main contract + appendices/supplements.** Same issuer, formally cross-referenced. The main contract states the total, the appendices break it down. Issues to expect: totals that don't match line-item sums, referenced appendices missing or outdated, version mismatches between main body and supplements.
 
-Populate the matrix using output from `entity-extraction`. An empty cell means the field was not found in that document — this is absence, not necessarily an error. But absence in a field that should be present is itself a finding.
+2. **Multi-source bundle.** Loan application + income certificate + bank statement + credit report + property appraisal. Different issuers, different formats, same borrower/case. Issues to expect: identity drift across docs (name spellings, employer name variants), value contradictions (income claimed vs. observed), suspicious consistency (multiple docs with identical formatting/phrasing → possible fabrication).
 
-## Contradiction Types
+When authoring a rule, name the pattern it targets. The check.py shape differs between the two — the contract+appendices pattern expects formal references and reciprocal links; the multi-source pattern expects normalization (entity reconciliation across formats).
 
-### Hard Contradictions
+## Contradiction taxonomy (what the rule may need to detect)
 
-Exact mismatches in fields that must be identical across documents:
+A cross-doc rule may flag one or more of these:
 
-- **Identity mismatch**: Name spelled differently, ID number differs by digits, date of birth inconsistent.
-- **Amount mismatch**: Main contract states 5,000,000 but appendix line items sum to 4,850,000. Income certificate says 82,000/month but application says 85,000/month.
-- **Date mismatch**: Contract effective date in the main body differs from the date in an appendix.
+### Hard contradictions
+Exact mismatches in fields that must be identical across docs.
+- Identity field mismatch (name, ID, DoB).
+- Amount mismatch beyond tolerance (totals, line items, reported incomes).
+- Date mismatch on fields that should be identical (effective date, signing date).
 
-Hard contradictions are binary. Either the values match (within defined tolerance) or they do not.
+Hard contradictions are binary. Either the values match (within defined tolerance) or they don't.
 
-### Soft Contradictions
+### Soft contradictions
+Values not directly inconsistent but **implausible** when considered together.
+- Monthly income claimed at one level; bank statement averages significantly below it.
+- Property appraisal close to the loan amount (high LTV — technically possible, but a signal).
+- Employment dates with multi-month gaps across documents.
 
-Values that are not directly inconsistent but are implausible when considered together:
+Soft contradictions need thresholds and judgment. They are findings, not verdicts — the rule should specify whether they trigger FAIL, WARNING, or just evidence-collection for downstream review.
 
-- Monthly income claimed as 100,000 but bank statement average deposits are 5,000.
-- Property appraised at 3,000,000 but loan amount is 2,800,000 (93% LTV — technically possible but suspicious).
-- Employment start date 2019-03 on the application but 2019-06 on the income certificate — a 3-month gap that could be rounding or could be fabrication.
+### Cross-reference failures
+Structural integrity problems within formally linked documents.
+- Main contract references "Appendix B — Payment Schedule" but Appendix B is missing or has a different title.
+- Appendix references a clause that doesn't exist in the main contract.
+- Missing reciprocal reference: appendix references main contract, but main contract doesn't list appendix.
+- Version mismatch: main contract dated one date, appendix dated a much later date with different terms.
 
-Soft contradictions require thresholds and judgment. They are findings, not verdicts.
+See `references/contradiction-taxonomy.md` for the field-level taxonomy with tolerances and severity templates the rule designer can borrow.
 
-### Cross-Reference Failures
+## Severity classification (rule-level decision)
 
-Structural integrity problems within formally linked documents:
+Not all contradictions carry the same weight. The rule must specify how its findings map to severity:
 
-- Main contract references "Appendix B — Payment Schedule" but Appendix B is titled "Technical Specifications" or is missing entirely.
-- Appendix references a clause in the main contract that does not exist in the provided version.
-- Missing reciprocal reference: Appendix C references the main contract, but the main contract does not list Appendix C.
-- Version mismatch: main contract dated January, appendix dated March with different terms.
+| Severity | Typical example |
+|----------|-----------------|
+| Critical | Identity field mismatch (different ID across docs) |
+| High | Significant financial amount discrepancy |
+| Medium | Date or employment-detail mismatch |
+| Low | Formatting / abbreviation difference ("ABC Corp" vs "ABC Corporation") |
 
-See `references/contradiction-taxonomy.md` for the full field-level taxonomy with tolerances and severity classifications.
+The actual thresholds are domain-specific. The developer user sets them per field; the rule's design should leave room for the configured values rather than hardcode percentages.
 
-## Severity Classification
+## Fraud-signal patterns the rule may surface
 
-Not all contradictions are equal. Classify by impact:
+Some patterns are visible only at the case level:
 
-| Severity | Criteria | Example |
-|----------|----------|---------|
-| **Critical** | Identity field mismatch | ID number differs between documents |
-| **High** | Financial amount discrepancy > 10% | Income 85K vs bank avg 43K |
-| **Medium** | Date or employment detail mismatch | Employment start date 3 months apart |
-| **Low** | Formatting or abbreviation difference | "ABC Corp" vs "ABC Corp Ltd" |
+- **Consistent small discrepancies across docs**: e.g., every doc inflated by ~5%, every date shifted by exactly one month. Consistency-in-error suggests coordinated fabrication rather than honest mistakes.
+- **Suspicious doc consistency**: multiple docs from supposedly different issuers using identical formatting / phrasing / typos.
+- **Values at regulatory thresholds**: LTV exactly at the limit, DTI exactly at the limit. One coincidence is harmless; a pattern across the case is a signal.
+- **Temporal impossibilities**: income certificate issued before employment start; bank statement covering a period before account opening; appraisal dated after loan disbursement.
 
-The developer user sets severity thresholds per field in the project configuration. The defaults above are starting points. Adjust based on the business context — in some scenarios, a 5% amount discrepancy is critical; in others, 15% is acceptable.
+If the rule's job includes any of these, encode them. These are **signals for escalation**, not conclusions — the rule should output "flagged" with evidence, and let the developer user or downstream review process determine the final verdict.
 
-## Fraud Signal Patterns
+## Designing the case-walk in check.py
 
-Cross-document analysis reveals patterns that single-document review cannot detect. Flag these — do not accuse, flag:
+For a cross-doc rule, a typical check.py:
 
-- **Consistent small discrepancies across documents.** Income inflated by exactly 5% in every document. Dates shifted by exactly one month. This consistency in error suggests coordinated fabrication rather than honest mistakes.
-- **Suspicious document consistency.** Multiple documents from supposedly different issuers use identical formatting, identical phrasing, or identical typos. Legitimate documents from different organizations look different.
-- **Values at regulatory thresholds.** LTV ratio at exactly 69.9% when the limit is 70%. DTI at exactly 49.8% when the limit is 50%. One occurrence is coincidence. A pattern across the case is a signal.
-- **Temporal impossibilities.** Income certificate issued before the employment start date. Bank statement covering a period before the account opening date. Appraisal dated after the loan disbursement.
+1. Receives the case (list of doc paths/handles + classification metadata).
+2. Selects the **starting document** of the class declared in the rule.
+3. Extracts the **anchor entity** (using entity-extraction).
+4. Locates the **target document(s)** in the case by the anchor or by formal reference.
+5. Extracts the **target entity** from each target doc.
+6. Applies the **consistency check** per the rule's PASS criteria.
+7. Returns:
+   - verdict (PASS / FAIL / WARNING / NOT_APPLICABLE)
+ - evidence (the cells of the comparison matrix that drove the verdict, with source-doc + page references)
+   - confidence (per `confidence-system`)
 
-These are signals for escalation, not conclusions. Present them with evidence and let the developer user or downstream review process make the determination.
-
-## Workflow Sequence
-
-The recommended sequence for cross-document verification within a case:
-
-1. **Identify the case boundary.** Which documents belong together? Use shared identifiers (borrower name, loan number, contract reference) to group documents into cases.
-2. **Extract anchors.** Run `entity-extraction` on each document independently. Collect the shared fields.
-3. **Build the matrix.** Populate the comparison matrix. Flag empty cells.
-4. **Detect contradictions.** Apply hard/soft/cross-reference checks per `references/contradiction-taxonomy.md`.
-5. **Classify severity.** Assign severity per the configured thresholds.
-6. **Scan for fraud signals.** Run pattern checks across the matrix.
-7. **Produce the report.** Output the case-level consistency report with all findings.
+The comparison matrix is rule-specific — only the fields this rule needs. Building a generic "all entities × all docs" matrix is expensive and pollutes the evidence trail.
 
 ## Integration
 
-**Inputs:**
-- Entity extraction results from `entity-extraction` (the raw field values per document).
-- Compliance judgment results from `compliance-judgment` (per-document pass/fail already computed).
+**Inputs to the rule's check.py at runtime:**
+- Case structure (set of related documents + identifiers).
+- Entity extraction available per-doc (skill: `entity-extraction`).
+- Compliance judgment may have already produced per-doc verdicts (skill: `compliance-judgment`) that this rule can use as part of its inputs.
 
 **Outputs:**
-- Case-level consistency report: the comparison matrix, all contradictions found, severity classifications, and fraud signal flags.
+- A case-level verdict plus the comparison-matrix slice that justifies it.
 
 **Feeds into:**
-- `confidence-system`: Cross-document contradictions lower confidence in affected fields.
-- `evolution-loop`: Recurring contradiction patterns trigger workflow refinement.
-- `dashboard-reporting`: Case-level view alongside document-level results.
+- `confidence-system`: cross-doc contradictions are a strong signal, often lowering confidence in affected fields.
+- `evolution-loop`: recurring contradiction patterns the rule didn't anticipate trigger workflow refinement.
+- `dashboard-reporting`: case-level view alongside per-doc results.
+
+## Ground-truth principle
 
-**Ground truth principle:** User and end-user contradiction reports feed back as ground truth. When a user or end-user reports a cross-document inconsistency that the system missed, that report is prior to agent judgment. Log it, learn from it, and adjust detection thresholds accordingly. The system's job is to catch what humans catch — and then go further.
+When the developer user or end user reports a cross-doc inconsistency that this rule missed, that report is prior to agent judgment. Log it, treat it as a corner case (`corner-case-management`) or as a trigger for rule refinement, and adjust detection thresholds accordingly. The rule's job is to catch what humans catch — and then go further.

package/template/skills/en/dashboard-reporting/SKILL.md

@@ -1,107 +1,132 @@
 ---
 name: dashboard-reporting
 tier: meta-meta
-description: Generate HTML dashboards for developer users to visualize verification results, system progress, and quality metrics. Use when a testing round completes, when production batches finish processing, when the developer user wants to see the system's status, or at any point where visual reporting would help communicate progress. Dashboards should be self-contained HTML files that can be opened by double-clicking. Also use when the developer user asks about results, accuracy, or system health.
+description: Generate HTML dashboards for developer users to visualize verification results, system progress, and quality metrics. Use when a testing round completes, when production batches finish processing, when the developer user wants visual reporting, or when they explicitly ask for it. Dashboards are self-contained HTML files. Use this skill **when there's something visual worth showing** — not as a default deliverable. For routine status updates use KC's TUI. The dashboard is a complement to direct reporting, not a substitute.
 ---
 
 # Dashboard Reporting
 
-The dashboard is the developer user's window into the system. They should not need to read logs or parse JSON to understand what is happening. Give them a clear, visual summary that leads with what matters.
+The dashboard is one channel — and not always the most economical one — for letting the developer user see what's going on. KC already reports status directly in the TUI; the HTML dashboard exists for things that are **worth seeing visually**: distributions, timelines, heatmaps, side-by-side comparisons, drill-down tables.
 
-## Dashboard Types
+Don't treat dashboard generation as a checkbox to satisfy this skill. Treat it as a deliverable the developer user actually asked for, or where a picture genuinely saves them time over reading TUI output or JSON.
 
-### Results Dashboard
-Generated after each batch of documents is processed.
+## Minimum vs. nice-to-have
 
-Key elements:
-- **Summary bar**: Total documents, pass rate, fail rate, missing rate, error rate.
-- **Per-rule breakdown**: Table showing each rule's pass/fail counts, accuracy, and average confidence.
-- **Failed cases**: List of documents that failed, with the rule, extracted value, expected value, and comment. Sortable and filterable.
-- **Confidence distribution**: Histogram showing how many results fall in each confidence band.
+When the developer user asks for a dashboard, **start with the minimum and expand only if it adds real value**.
 
-### Progress Dashboard
-Generated on demand to show the system's evolution.
+### Minimum
 
-Key elements:
-- **Lifecycle status**: Which rules are in which phase (skill testing, workflow testing, production, stable).
-- **Rule catalog**: Table of all rules with their current status, accuracy, and version.
-- **Evolution timeline**: For each rule, how many iterations it took, what was the accuracy at each step.
-- **Model tier assignments**: Which model is being used for each step of each rule.
+A useful dashboard at the floor:
+- A summary header: total documents, top-line pass/fail/missing counts.
+- A per-rule table: rule_id, accuracy, pass / fail / NA counts, optional confidence column.
+- A list of failed cases the user can click into for details (rule, extracted value, expected value, comment).
 
-### Quality Dashboard
-Generated after quality control reviews.
+That's enough to ship. If the user can answer "is this batch healthy and which rules failed" in 3 seconds, the minimum is done.
 
-Key elements:
-- **Accuracy over time**: Line chart showing per-rule and overall accuracy across batches.
-- **Sampling rate over time**: Showing how monitoring is decreasing (or not).
-- **Flagged issues**: Open issues that need developer user attention.
-- **Cost metrics**: LLM calls and tokens per document, per rule.
+### Nice-to-have
 
-## Feedback Collection
+Add these only when they're justified by the data on hand or the user's actual need:
+- Confidence distribution histogram (useful when confidence is calibrated and the user cares about the distribution shape).
+- Accuracy-over-time line chart (useful only when there's enough history to draw a meaningful curve).
+- Per-product-type / per-issuer breakdown (useful when the corpus has meaningful segmentation).
+- Cost metrics (useful when cost is a live concern; otherwise skip).
+- Drill-down navigation (summary → rule → document).
+- Inline feedback widgets (correction-on-click, flag-as-wrong).
 
-Every dashboard must include mechanisms for users to report errors and comment directly on verification results. This is not a nice-to-have — user feedback is the most valuable data source in the system.
+Don't add a section to look thorough. An empty "Confidence distribution" chart with no calibrated data is worse than no chart.
 
-### Developer User Feedback
+## Dashboard types (when to use which)
 
-Developer users see full result detail. Their feedback interface should support:
-- **Field-level correction**: Click on an extracted value, provide the correct value.
-- **Result override**: Change a pass to fail (or vice versa) with a reason.
-- **Rule re-evaluation request**: Flag a result for re-processing with a different approach.
-- **Comment**: Free-text annotation on any result.
+### Results dashboard
+After a batch of documents is processed. The minimum above usually covers it.
 
-### End User Feedback
+### Progress dashboard
+On demand, to show the system's evolution across phases. Lifecycle status per rule, rule catalog table, evolution timeline. Mostly useful when the developer user wants a "where are we" snapshot mid-build.
 
-End users of the verification app see simplified results. Their interface should support:
-- **Flag as wrong**: One-click to report a result they believe is incorrect.
-- **Add comment**: Brief text explaining what they think is wrong.
-- **Severity indicator**: How impactful is this error? (Critical / Important / Minor)
+### Quality dashboard
+After QC review cycles. Accuracy-over-time, sampling rate trend, flagged issues, cost. Useful when QC has accumulated enough cycles to show a trend.
 
-### Feedback as Ground Truth
+If only one of the three would actually help the developer user right now, build only that one. Don't generate all three by default.
 
-User-reported errors are ground truth. They override the coding agent's judgment and the worker LLM's output. The feedback data flow:
+## Feedback collection (optional but recommended when applicable)
 
-1. User submits feedback via dashboard → stored as structured record.
-2. Record schema: `{result_id, trace_id, reporter_role, feedback_type, original_result, corrected_value, comment, timestamp}`.
-3. Feedback records are fed into the `evolution-loop` as confirmed failures.
-4. Dashboard surfaces feedback trends: correction rate over time, most-reported issues, rules with highest user correction rates.
+When the dashboard is destined for an audience that's going to review the results (developer user, end user, domain expert), include feedback widgets. When the dashboard is purely for developer-user inspection mid-build, feedback widgets are usually overkill — they pretend at a workflow the user isn't going to follow.
 
-Build the feedback collection mechanism alongside the dashboard generation — they are not separate features. Every generated HTML dashboard should include the feedback UI, even if it initially writes to a local JSON file that the coding agent reads on the next iteration.
+### Developer-user feedback
+
+Full result detail visible. Useful widgets:
+- Field-level correction: click an extracted value, provide the right one.
+- Result override: change pass to fail (or vice versa) with a reason.
+- Comment: free-text annotation on any result.
+
+### End-user feedback
+
+Simplified results visible. Useful widgets:
+- Flag-as-wrong: one-click to report a result believed incorrect.
+- Comment: brief text explanation.
+- Severity indicator: critical / important / minor.
+
+### Feedback as ground truth
+
+User-reported errors are ground truth. They override agent judgment and worker-LLM output. Flow:
+
+1. Submit via dashboard → stored as structured record.
+2. Schema: `{result_id, trace_id, reporter_role, feedback_type, original_result, corrected_value, comment, timestamp}`.
+3. Records feed into `evolution-loop` as confirmed failures.
+4. Surface feedback trends in subsequent dashboards (correction rate over time, most-reported issues, rules with highest correction rates).
 
 ## Technology
 
-Self-contained HTML with embedded CSS and JavaScript. Requirements:
-- **No external dependencies.** No CDN links, no npm packages, no server. Everything is inlined.
-- **No server required.** The developer user double-clicks the HTML file to open it in their browser.
-- **Responsive layout.** Should work on both desktop and mobile screens.
-- **Dark/light mode.** Respect the system preference or provide a toggle.
+Self-contained HTML with embedded CSS / JavaScript.
+- **No external dependencies.** No CDN links, no npm packages, no server. Everything inlined.
+- **No server required.** Developer user double-clicks the HTML file.
+- **Responsive layout.** Should work on desktop and mobile.
+- **Dark/light mode** — respect system preference or provide a toggle.
 
-For charts, use inline SVG or a lightweight chart library that can be embedded (e.g., Chart.js or lightweight alternatives, inlined as a script tag).
+For charts, use inline SVG or a lightweight chart library inlined as a `<script>` tag.
 
-## Data Sources
+## Data sources
 
 Dashboards read from:
 - `Output/` for verification results.
 - `logs/` for evolution and testing history.
-- `versions.json` for current system state.
-- QC review records (stored alongside Output/).
+- `versions.json` (or git log) for current system state.
+- QC review records (stored alongside `Output/`).
 
-The dashboard generation script should accept input paths and produce a single HTML file.
+The generation script should accept input paths and produce a single HTML file.
 
-## Generation Triggers
+## Generation triggers
 
-Generate dashboards automatically after:
-- Each testing round completes (skill testing or workflow testing).
-- Each production batch finishes processing.
-- Each quality control review cycle.
-- Developer user explicitly requests it.
+Generate dashboards when:
+- A testing round completes AND there's enough data to be worth visualizing.
+- A production batch finishes AND the developer user wants a visual.
+- A QC review cycle completes.
+- The developer user explicitly requests one.
 
-Store generated dashboards in `Output/dashboards/` with timestamps in filenames for history.
+Don't auto-generate on every minor event — the dashboards pile up fast and the user won't open most of them. When unsure, ask the user ("Want me to generate a dashboard?") instead of producing one unprompted.
 
-## Design Principles
+Store generated dashboards in `Output/dashboards/` with timestamped filenames for history.
 
-- **Lead with the summary.** The developer user should understand the system's health in 3 seconds.
-- **Drill down on demand.** Summary → rule-level → document-level. Do not overwhelm with details upfront.
+## Design principles
+
+- **Lead with the summary.** Developer user should understand health in 3 seconds.
+- **Drill down on demand.** Summary → rule-level → document-level. Don't overwhelm with details upfront.
 - **Color coding.** Green for pass/healthy, red for fail/critical, yellow for warning/attention. Simple and universal.
-- **Actionable.** Every flagged issue should suggest what to do next.
+- **Actionable.** Every flagged issue should suggest a next step.
+
+A starter script is available in `scripts/generate_dashboard.py`. Adapt to the specific scenario — and feel free to trim the script when half its sections wouldn't have content. A small dashboard that answers the user's question beats a comprehensive one they don't need.
+
+## Relationship to TUI reporting
+
+KC's TUI already supports rich status reporting during the run. Use TUI for:
+- Ongoing progress narration.
+- Per-phase summaries.
+- Quick "what just happened" updates.
+- Anything that can be communicated in a few lines of text.
+
+Use HTML dashboards for:
+- Visual artifacts that wouldn't fit (distributions, charts, filterable tables).
+- Hand-off to non-KC users (developer-user reviewing later, end-user audience).
+- Persistent records the user wants to revisit.
 
-A starter script is available in `scripts/generate_dashboard.py`. Adapt it to the specific business scenario.
+When in doubt, prefer the TUI. A short status message the user is already reading beats a dashboard they have to open.