# How the Humanizer Package Validator Enforces Pattern Numbering

> Discover how the humanizer package validator enforces sequential pattern numbering by parsing SKILL.md headings and cross-referencing with the README for perfect synchronization.

- Repository: [Siqi Chen/humanizer](https://github.com/blader/humanizer)
- Tags: how-to-guide
- Published: 2026-09-11

---

**The humanizer package validator enforces sequential pattern numbering by parsing [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) for `### <number>.` headings, verifying they form an unbroken sequence starting at 1, and cross-referencing those numbers against the README table to ensure complete synchronization.**

The `blader/humanizer` repository maintains strict documentation standards through automated validation. Understanding how the humanizer package validator enforces pattern numbering helps contributors ensure their skill submissions meet structural requirements before CI/CD pipelines reject malformed packages.

## Parsing and Validating SKILL.md Numbering

The validator script ([`scripts/validate-package.py`](https://github.com/blader/humanizer/blob/main/scripts/validate-package.py)) begins its enforcement by extracting pattern identifiers directly from the skill definition file.

### Extracting Pattern Numbers with Regular Expressions

On lines 66-69, the script uses a multiline regular expression to capture integers from level-3 headings:

```python
pattern_numbers = [
    int(number)
    for number in re.findall(r"(?m)^### ([0-9]+)\. ", SKILL)

]

```

This regex `(?m)^### ([0-9]+)\. ` specifically targets headings formatted as `### 1.`, `### 2.`, etc., ignoring any text that follows the number and period.

### Enforcing Sequential Integrity

Immediately after extraction (lines 70-73), the validator ensures the collected numbers represent a continuous range without gaps or duplicates:

```python
pattern_count = len(pattern_numbers)
if pattern_count == 0 or pattern_numbers != list(range(1, pattern_count + 1)):
    raise SystemExit(
        f"Number SKILL.md patterns from 1 upward without gaps: {pattern_numbers}"
    )

```

This check guarantees at least one pattern exists and that the sequence runs exactly from 1 through N, where N represents the total pattern count.

## Synchronizing README.md with SKILL.md

Beyond validating internal consistency, the script ensures the README documentation accurately reflects the patterns defined in the skill file.

### Cross-Referencing the Pattern Table

Lines 74-76 parse the README's markdown table to extract the "Pattern" column values:

```python
readme_numbers = [
    int(number) for number in re.findall(r"(?m)^\| ([0-9]+) \|", README)
]

```

The validator then compares these extracted values against the [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) sequence (lines 77-80):

```python
if sorted(readme_numbers) != pattern_numbers:
    raise SystemExit(
        f"List patterns 1 through {pattern_count} once each in the README tables: {sorted(readme_numbers)}"
    )

```

This ensures the README contains exactly the same set of numbers as the skill definition, preventing orphaned patterns or documentation drift.

### Validating the README Section Heading

On lines 81-82, the script performs a final consistency check by verifying the README contains a section titled "The N patterns", where N matches the detected pattern count. This enforces structural uniformity across all humanizer packages in the repository.

## Validation Failure Examples

When contributors violate numbering rules, the validator provides specific error messages to facilitate rapid correction.

**Missing sequence numbers** trigger the following output when [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) contains `### 1.` followed by `### 3.`:

```text
Number SKILL.md patterns from 1 upward without gaps: [1, 3]

```

**README mismatches** produce errors like this when the table omits pattern 2:

```text
List patterns 1 through 3 once each in the README tables: [1, 3]

```

Successful validation yields a clean exit message: `Humanizer package v3.0.0 is valid`.

## Summary

- The validator extracts pattern numbers from [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) using the regex `(?m)^### ([0-9]+)\. ` to identify all `### <number>.` headings.

- It enforces a strict sequence from 1 to N without gaps by comparing the extracted list against `range(1, pattern_count + 1)`.
- The script parses README tables with `(?m)^\| ([0-9]+) \|` and mandates exact numerical parity with the skill file.
- A descriptive section heading "The N patterns" must exist in the README, where N equals the total pattern count.
- All validation logic resides in [`scripts/validate-package.py`](https://github.com/blader/humanizer/blob/main/scripts/validate-package.py), which aborts with actionable error messages upon detecting inconsistencies.

## Frequently Asked Questions

### What regex pattern does the humanizer validator use to find pattern numbers in SKILL.md?

The validator uses `(?m)^### ([0-9]+)\. `, a multiline regex that matches level-3 markdown headings starting with a number and period. This pattern appears on line 66 of [`scripts/validate-package.py`](https://github.com/blader/humanizer/blob/main/scripts/validate-package.py) and captures only the numeric portion of headings like `### 1.` or `### 15.`.

### Why does the humanizer package validator check both SKILL.md and README.md?

The dual-file validation prevents documentation synchronization errors. While [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) contains the authoritative pattern definitions, the README table serves as the public-facing index. The validator ensures both files list identical pattern numbers, eliminating scenarios where a pattern exists in the skill file but remains undocumented in the README, or vice versa.

### What error message appears when pattern numbering contains gaps?

When [`SKILL.md`](https://github.com/blader/humanizer/blob/main/SKILL.md) contains non-sequential numbering such as 1, 3, 4, the validator raises `SystemExit` with the message: `"Number SKILL.md patterns from 1 upward without gaps: [1, 3, 4]"`. This explicit feedback allows contributors to identify exactly which numbers are present and which are missing from the expected sequence.

### Does the validator accept patterns numbered starting from 0 instead of 1?

No. The validation logic on lines 70-73 explicitly requires the sequence to match `range(1, pattern_count + 1)`, which begins at 1. Any pattern file starting at 0 or skipping the integer 1 will fail validation with a gap error, enforcing the repository's 1-based numbering convention.