Skip to main content

Handle Technical Debt

"Why did my score drop after I ignored an error?"

When you suppress a finding in Zenzic — via an inline comment or a per-file config entry — you are not erasing the problem. You are assuming responsibility for it. That assumption has a cost: Technical Debt Points deducted from your quality score.

This guide explains how to read the debt, understand the cost formula, and reduce it over time.

Reading the Score Output​

After running zenzic score, you may see an extra line below the score table:

Score: 93/100
! Technical Debt (Suppressions): -7 pts
Suppression Audit: 7/30 (inline: 5, per-file: 2)

This means:

  • 7 active suppressions are hiding findings from the audit stream.
  • 5 are inline zenzic:ignore comments in Markdown/MDX files.
  • 2 are per-file entries in governance.per_file_ignores.
  • The debt formula reduced the score by 7 pts.

The Cost Formula​

extdebt=n ext{debt} = n

Where:

  • nn = total active suppressions (inline + per-file)
  • cap = governance.suppression_cap in .zenzic.toml (default: 30)

The debt cost is flat: each suppression always costs 1 pt.

SuppressionsDebtScore (from 100)
00 pt100
1010 pt90
3030 pt70
3131 pt69
3535 pt65

When suppressions exceed the configured cap, the run still hard-fails via the governance gate (suppression_cap) even though debt remains linear. The score gate (fail_under) and the cap gate are orthogonal and evaluated independently.

Step 1: See What You Are Hiding​

Run a sovereign audit to see all findings that are currently suppressed:

zenzic check all --audit

The --audit flag bypasses all inline zenzic:ignore comments and all governance.per_file_ignores entries. It shows the true state of your documentation.

Compare the --audit output with a normal zenzic check all run to see exactly which findings are hidden.

Step 2: Understand the Rule's Cost​

For each suppressed finding, use zenzic explain to see its scoring impact:

zenzic explain Z601

The output shows:

  • The rule's scoring tier (structural / navigation / content / brand)
  • The penalty per occurrence (pts/occurrence)
  • The per-file suppression status from your current .zenzic.toml

Step 3: Fix vs Acknowledge​

For each suppressed finding, make an explicit decision:

Fix it (reduce debt)​

Remove the suppression and fix the underlying issue:

  1. Delete the <!-- zenzic:ignore ZXXX --> comment from the Markdown line.
  2. Or remove the entry from governance.per_file_ignores.
  3. Then fix the actual violation (update the link, remove the obsolete term, etc.).
  4. Run zenzic check all to verify.

Acknowledge it (document the intent)​

If the suppression is genuinely intentional (historical reference, migration context, etc.):

  1. Keep the suppression but add a prose comment explaining why.
  2. Prefer per-file suppression over inline comments for structural exceptions — it centralises the policy in .zenzic.toml.
  3. Adjust governance.suppression_cap if your project has a legitimately higher baseline.

Step 4: Adjust the Governance Cap​

If your project has a known-good suppression baseline that is higher than 30, raise the cap in .zenzic.toml:

[governance]
suppression_cap = 45           # adjusted for a large i18n project
suppression_cap_fail_hard = true

Setting the cap to the current suppression count gives you a governance floor: new suppressions will immediately escalate the cost and eventually trigger suppression_cap_fail_hard.

Why Security Violations Cannot Be Suppressed​

Findings in the Z2xx Security Gate category — Z201 CREDENTIAL_SECRET, Z202 PATH_TRAVERSAL, Z203 PATH_TRAVERSAL_FATAL, and Z204 FORBIDDEN_TERM — cannot be suppressed by any mechanism.

A <!-- zenzic:ignore: Z2XX --> comment is silently ignored. The finding is still emitted. The exit code is still 2 or 3. The score collapses to 0.

This is by design. Security findings are facts, not style opinions. You cannot assume responsibility for a credential leak and call it a validated exception.

Reference​