Merge pull request #2 from jet52/claude/repackage-skill-upload-EYBkb

jet52 · web-flow · commit c179ae1ab4f7 · 2026-02-19T11:27:25.000-06:00
Claude/repackage skill for checking appellate briefs against ND rules
diff --git a/README.md b/README.md
@@ -2,7 +2,161 @@
 
 Checks appellate brief PDFs for compliance with the North Dakota Rules of Appellate Procedure and produces an HTML compliance report with a recommended action: **Accept**, **Correction Letter**, or **Reject**.
 
-## Quick Start
+---
+
+## Installing the Skill in Claude (Browser)
+
+This section walks you through adding the Brief Compliance Checker to your Claude account so you can use it directly in a browser chat session. No programming knowledge is required.
+
+### What You Need Before You Start
+
+- A Claude account at [claude.ai](https://claude.ai) with a Pro, Team, or Enterprise plan (the skill requires the ability to upload files and use projects).
+- The **`brief-compliance.zip`** file from this repository. You can download it from the repository's file list by clicking on `brief-compliance.zip` and then clicking the download button.
+
+### Step-by-Step Installation
+
+#### 1. Open Claude and Create a New Project
+
+1. Go to [claude.ai](https://claude.ai) and sign in.
+2. In the left sidebar, click **Projects**.
+3. Click **Create Project** (or the **+** button).
+4. Give your project a name, such as "Brief Compliance Checker".
+5. Click **Create**.
+
+#### 2. Upload the Skill Files to Project Knowledge
+
+> **Important — upload to the *project*, not to a chat.** Files uploaded to Project Knowledge are available in every chat you open inside that project. If you instead drag a file into a regular chat window, it only exists in that single conversation and disappears when you start a new one. Make sure you are adding the file through the project settings, not the chat input box.
+
+1. Inside your new project, look for the **Project Knowledge** section (sometimes labeled "Project files" or accessible via a paperclip/attachment icon in the project settings).
+2. Click **Upload** or **Add files**.
+3. Select the **`brief-compliance.zip`** file you downloaded earlier.
+4. Wait for the upload to finish. Claude will unpack and index the contents automatically.
+
+The ZIP file contains everything the skill needs: the analysis scripts, the bundled North Dakota appellate rules, check definitions, and the skill instructions.
+
+#### 3. Set the Project Instructions
+
+1. In your project settings, find the **Custom Instructions** field (also called "System prompt" or "Project instructions").
+2. Open the file `SKILL.md` from this repository (or extract it from the ZIP). Copy its entire contents.
+3. Paste the contents into the Custom Instructions field.
+4. Save the project settings.
+
+These instructions tell Claude how to run the compliance analysis step by step whenever you upload a brief.
+
+#### 4. Verify the Installation
+
+1. Open a new chat inside the project.
+2. Type: **"Are you ready to check a brief for compliance?"**
+3. Claude should respond confirming it can analyze appellate briefs against the North Dakota Rules.
+
+If Claude does not seem to recognize the skill, double-check that:
+- The ZIP file was uploaded to the project (not just to a regular chat).
+- The SKILL.md contents were pasted into the project's Custom Instructions.
+
+### A Note on Scope
+
+The skill lives inside the project you created — it is not available in other projects or in regular (non-project) chats. Claude does not currently offer a way to install a skill globally across your entire account.
+
+In practice this isn't a limitation: just **open all your brief-checking chats inside this one project**. You can create as many chats as you like within a project, and every one of them will have access to the skill files and instructions automatically. Think of the project as a dedicated "Brief Compliance Checker" app that's always ready when you need it.
+
+---
+
+## Using the Skill
+
+Once installed, using the skill is straightforward. You upload a PDF of an appellate brief, and Claude produces a detailed compliance report.
+
+### Checking a Brief
+
+1. **Open a chat** inside your Brief Compliance Checker project.
+2. **Drag and drop** your brief PDF into the chat window (or click the attachment/paperclip icon and select the file).
+3. **Tell Claude what to do.** You can simply say:
+
+   > "Check this brief for compliance."
+
+   Or be more specific if you know the brief type:
+
+   > "Check this appellant brief for compliance."
+   >
+   > "This is an appellee brief. Please run a compliance check."
+   >
+   > "Check this reply brief."
+
+4. **Wait for the analysis.** Claude will work through several phases automatically:
+   - **Extraction** — reads the PDF and measures formatting (paper size, margins, fonts, spacing, page count).
+   - **Mechanical checks** — compares measurements against Rule 32 requirements.
+   - **Semantic checks** — reads the brief text and evaluates whether required sections are present and adequate (Table of Contents, Statement of Issues, Argument, etc.).
+   - **Report generation** — combines all results into an HTML compliance report.
+
+5. **Review the results.** Claude will:
+   - State the **recommended action**: Accept, Correction Letter, or Reject.
+   - Summarize any **failed checks**, grouped by severity.
+   - Provide a **downloadable HTML report** with full details.
+
+### Understanding the Report
+
+The HTML report has several sections:
+
+- **Recommended Action** — a color-coded banner at the top:
+  - **Green (Accept)** — the brief appears to comply with all rules.
+  - **Yellow (Correction Letter)** — there are formatting issues that should be corrected, but the brief is not rejected outright.
+  - **Red (Reject)** — there are serious compliance failures that warrant rejection.
+
+- **Failed Checks** — grouped into three severity levels:
+  - **Critical (Reject)** — violations that alone justify rejection (e.g., wrong paper size, font too small, over the page limit).
+  - **Correction Required** — problems that should be fixed but don't rise to rejection level (e.g., margin too narrow, missing paragraph numbering).
+  - **Advisory Notes** — minor issues or observations (e.g., oral argument notation not found, font style question).
+
+- **Passed Checks** — an expandable section listing everything that passed. Click to expand.
+
+- **Not Applicable** — checks that don't apply to this brief type (e.g., amicus-specific checks on an appellant brief).
+
+Each failed check shows:
+- A **check ID** (e.g., FMT-006) for reference.
+- The **rule citation** (e.g., Rule 32(a)(5)), linked to the official rule text on ndcourts.gov.
+- A **message** explaining what was found.
+- **Details** with specifics — for font size issues, this includes a per-page breakdown showing which pages have undersized text and how many characters are affected.
+
+### Tips for Best Results
+
+- **Specify the brief type** if you know it. Auto-detection works for most appellant briefs but sometimes misidentifies appellee and reply briefs. Telling Claude the type up front avoids this.
+
+- **Known false positives to watch for:**
+  - **Font size (FMT-006)**: Page numbers, footnote markers, and superscripts are often smaller than 12pt. The report now categorizes these separately (body text vs. header/footer vs. superscript) so you can see whether the issue is real body text or just incidental small characters. If the only noncompliant characters on a page are in the header/footer or superscript categories, the severity is downgraded to a note rather than a rejection.
+  - **Line spacing (FMT-009)**: The spacing detector can misread certain PDF encodings. If the brief was prepared in a standard word processor with double spacing selected, a spacing failure is likely a false positive.
+  - **Bottom margin (FMT-005)**: Page numbers at the bottom of the page are measured as content, which makes the bottom margin appear smaller than it really is.
+
+- **You can ask follow-up questions.** After the report is generated, you can ask Claude things like:
+  - "Which pages have the font size issue?"
+  - "Is the Table of Contents adequate?"
+  - "What would need to be fixed for this brief to be accepted?"
+  - "Can you re-check this as an appellee brief instead?"
+
+- **You can check multiple briefs** in the same chat session. Just upload another PDF and ask Claude to check it.
+
+### Brief Types Supported
+
+| Brief Type | Description | Page Limit |
+|------------|-------------|------------|
+| Appellant | Opening brief filed by the appealing party | 38 pages |
+| Appellee | Response brief filed by the opposing party | 38 pages |
+| Reply | Reply to the appellee's brief | 12 pages |
+| Cross-Appeal | Brief when both parties appeal | 38 pages |
+| Amicus Curiae | "Friend of the court" brief | 19 pages |
+
+### What Rules Are Checked
+
+The checker evaluates compliance against these North Dakota rules:
+
+- **Rule 28** — Required contents of briefs (sections, formatting of arguments, etc.)
+- **Rule 29** — Requirements for amicus curiae briefs
+- **Rule 30** — How to cite the record
+- **Rule 32** — Physical formatting (paper size, margins, fonts, spacing, page limits, cover requirements)
+- **Rule 34** — Oral argument notation on the cover
+- **Rule 3.4** — Privacy protection for personal identifiers in filings
+
+---
+
+## Developer Quick Start
 
 ```bash
 # Set up the virtual environment
@@ -27,7 +181,7 @@ python app.py
 - **`SKILL.md`** — Claude Code skill definition (deployed via symlink)
 - **`deploy_skill.py`** — Cross-platform script to deploy the skill to `~/.claude/skills/`
 
-## Skill Deployment
+## Skill Deployment (Claude Code CLI)
 
 The Claude Code skill (`/brief-compliance`) reads its files from `~/.claude/skills/brief-compliance/`. This repo is the single source of truth — `deploy_skill.py` copies the needed files into the skill directory.
 
diff --git a/core/checks_mechanical.py b/core/checks_mechanical.py
@@ -11,6 +11,7 @@
 from collections import Counter
 
 from core.constants import (
+    FONT_NONCOMPLIANT_THRESHOLD,
     MARGIN_TOLERANCE,
     MAX_CHARS_PER_INCH,
     MIN_BOTTOM_MARGIN,
@@ -124,20 +125,7 @@ def _check_fonts(metadata: BriefMetadata) -> list[CheckResult]:
     results = []
 
     # FMT-006: Font size >= 12pt — Rule 32(a)(5): "The typeface must be 12 point or larger"
-    if metadata.min_font_size is not None and metadata.min_font_size < MIN_FONT_SIZE_PT - FONT_SIZE_TOLERANCE:
-        results.append(CheckResult(
-            check_id="FMT-006", name="Minimum Font Size", rule="32(a)(5)",
-            passed=False, severity=Severity.REJECT,
-            message=f"Font size {metadata.min_font_size:.1f}pt found; minimum is {MIN_FONT_SIZE_PT}pt.",
-            details=f"Predominant font size: {metadata.predominant_font_size}pt. "
-                    f"Smallest detected: {metadata.min_font_size:.1f}pt.",
-        ))
-    else:
-        results.append(CheckResult(
-            check_id="FMT-006", name="Minimum Font Size", rule="32(a)(5)",
-            passed=True, severity=Severity.REJECT,
-            message=f"Font size meets the {MIN_FONT_SIZE_PT}pt minimum.",
-        ))
+    results.append(_check_font_size_per_page(metadata))
 
     # FMT-007: Max 16 characters per inch — Rule 32(a)(5): "no more than 16 characters per inch"
     cpi_issues = _check_chars_per_inch(metadata)
@@ -174,6 +162,128 @@ def _check_fonts(metadata: BriefMetadata) -> list[CheckResult]:
     return results
 
 
+def _classify_font_span(font: dict, page_height_pts: float) -> str:
+    """Classify a font span as 'header_footer', 'superscript', or 'body'.
+
+    - header_footer: origin_y in top or bottom 10% of the page
+    - superscript: PyMuPDF superscript flag (bit 0) set, or <=4 chars of
+      digit-only text at small size (catches footnote markers / ordinal suffixes)
+    - body: everything else
+    """
+    origin_y = font.get("origin_y", page_height_pts / 2)
+    top_zone = page_height_pts * 0.10
+    bottom_zone = page_height_pts * 0.90
+
+    if origin_y <= top_zone or origin_y >= bottom_zone:
+        return "header_footer"
+
+    flags = font.get("flags", 0)
+    is_superscript = bool(flags & 1)  # bit 0
+    if is_superscript:
+        return "superscript"
+
+    # Short digit-only text at small size — likely footnote marker or ordinal
+    chars = font.get("chars", 0)
+    if chars <= 4 and font["size"] < MIN_FONT_SIZE_PT - FONT_SIZE_TOLERANCE:
+        return "superscript"
+
+    return "body"
+
+
+def _check_font_size_per_page(metadata: BriefMetadata) -> CheckResult:
+    """FMT-006: Font size >= 12pt with per-page detail and categorisation."""
+    threshold = MIN_FONT_SIZE_PT - FONT_SIZE_TOLERANCE
+    page_issues: list[dict] = []  # one entry per page that has noncompliant chars
+
+    for p in metadata.pages:
+        if not p.fonts:
+            continue
+
+        page_height_pts = p.height_inches * 72.0
+        total_chars = 0
+        nc_body = 0
+        nc_hf = 0
+        nc_super = 0
+        min_size_on_page: float | None = None
+
+        for f in p.fonts:
+            char_count = f.get("chars", 1)
+            total_chars += char_count
+
+            if f["size"] < threshold:
+                category = _classify_font_span(f, page_height_pts)
+                if category == "header_footer":
+                    nc_hf += char_count
+                elif category == "superscript":
+                    nc_super += char_count
+                else:
+                    nc_body += char_count
+
+                if min_size_on_page is None or f["size"] < min_size_on_page:
+                    min_size_on_page = f["size"]
+
+        nc_total = nc_body + nc_hf + nc_super
+        if nc_total > 0:
+            page_issues.append({
+                "page": p.page_number + 1,
+                "total_chars": total_chars,
+                "nc_total": nc_total,
+                "nc_body": nc_body,
+                "nc_hf": nc_hf,
+                "nc_super": nc_super,
+                "min_size": min_size_on_page,
+            })
+
+    if not page_issues:
+        return CheckResult(
+            check_id="FMT-006", name="Minimum Font Size", rule="32(a)(5)",
+            passed=True, severity=Severity.REJECT,
+            message=f"Font size meets the {MIN_FONT_SIZE_PT}pt minimum.",
+        )
+
+    # Determine severity: REJECT if any page has >= threshold count, else NOTE
+    any_serious = any(pi["nc_total"] >= FONT_NONCOMPLIANT_THRESHOLD for pi in page_issues)
+    severity = Severity.REJECT if any_serious else Severity.NOTE
+
+    global_min = min(pi["min_size"] for pi in page_issues)
+    bad_page_nums = [pi["page"] for pi in page_issues]
+
+    page_label = "page" if len(bad_page_nums) == 1 else "pages"
+    message = (
+        f"Font size {global_min:.1f}pt found on {page_label} "
+        f"{_page_list(bad_page_nums)}; minimum is {MIN_FONT_SIZE_PT}pt."
+    )
+
+    # Build per-page breakdown
+    lines = [
+        f"Predominant font size: {metadata.predominant_font_size}pt. "
+        f"Smallest detected: {global_min:.1f}pt.",
+        "",
+        "Per-page breakdown:",
+    ]
+    for pi in page_issues:
+        pct = pi["nc_total"] / pi["total_chars"] * 100 if pi["total_chars"] else 0
+        parts = []
+        if pi["nc_body"]:
+            parts.append(f"{pi['nc_body']} body")
+        if pi["nc_hf"]:
+            parts.append(f"{pi['nc_hf']} header/footer")
+        if pi["nc_super"]:
+            parts.append(f"{pi['nc_super']} superscript")
+        breakdown = ", ".join(parts)
+        lines.append(
+            f"  Page {pi['page']}: {pi['nc_total']} of {pi['total_chars']:,} chars "
+            f"({pct:.1f}%) noncompliant — {breakdown}"
+        )
+
+    return CheckResult(
+        check_id="FMT-006", name="Minimum Font Size", rule="32(a)(5)",
+        passed=False, severity=severity,
+        message=message,
+        details="\n".join(lines),
+    )
+
+
 def _check_chars_per_inch(metadata: BriefMetadata) -> str:
     """Estimate characters per inch from page content."""
     # Use body pages only, skip cover
diff --git a/core/constants.py b/core/constants.py
@@ -18,6 +18,7 @@
 MIN_FONT_SIZE_PT = 12.0
 MAX_CHARS_PER_INCH = 16
 FONT_SIZE_TOLERANCE = 0.3  # pt tolerance for font size detection
+FONT_NONCOMPLIANT_THRESHOLD = 10  # chars per page: >= this count is REJECT, below is NOTE
 
 # --- Spacing ---
 # Double spacing is ~24pt between baselines for 12pt text.
diff --git a/core/pdf_extract.py b/core/pdf_extract.py
@@ -105,6 +105,8 @@ def _extract_page(page: fitz.Page, page_idx: int) -> PageInfo:
                         "name": span["font"],
                         "size": span["size"],
                         "flags": span["flags"],  # bold/italic flags
+                        "chars": len(span["text"].strip()),
+                        "origin_y": span["origin"][1],
                     })
 
     # Margins: find bounding box of all content
diff --git a/core/report_builder.py b/core/report_builder.py
@@ -218,7 +218,7 @@ def _css() -> str:
 .severity-correction { background: #fff8c5; color: #735c0f; }
 .severity-note { background: #f1f1f1; color: #586069; }
 .check-msg { margin-top: 0.4rem; font-size: 0.93rem; }
-.detail { margin-top: 0.3rem; font-size: 0.85rem; color: #586069; }
+.detail { margin-top: 0.3rem; font-size: 0.85rem; color: #586069; white-space: pre-line; }
 .checks-table { width: 100%; border-collapse: collapse; font-size: 0.9rem; }
 .checks-table th, .checks-table td { padding: 0.4rem 0.6rem; border-bottom: 1px solid #e1e4e8; text-align: left; }
 .checks-table th { background: #f6f8fa; font-weight: 600; }
diff --git a/tests/test_font_size_check.py b/tests/test_font_size_check.py
