How the Humanizer Package Validator Enforces Pattern Numbering

The humanizer package validator enforces sequential pattern numbering by parsing 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) 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:

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:

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:

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 sequence (lines 77-80):

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 contains ### 1. followed by ### 3.:

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

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

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 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, 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 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}