Skip to content

feat: Document-type awareness via --type flag (instructions/policy/persona/reference) #3

Description

@roli-lpci

Problem

lintlang currently treats every file as a generic system prompt. This creates false positives:

  • TOOLS.md (reference cheat sheet) gets flagged for missing priority ordering — irrelevant for reference docs
  • SOUL.md (persona guide) gets dinged for intentional vagueness — correct for persona, wrong for instructions
  • Policy files with NEVER / FORBIDDEN constraints get flagged as negative instructions — but these are security boundaries, not style issues

~30-40% of MEDIUM findings in real-world audits are type-context errors.

Proposed Solution

Add --type [instructions|policy|persona|reference] flag with auto-detection fallback:

class DocType(Enum):
    INSTRUCTIONS = "instructions"  # System prompts, SKILL.md files
    POLICY       = "policy"        # Red lines, security rules, hard constraints
    PERSONA      = "persona"       # Character, tone, soul docs
    REFERENCE    = "reference"     # Cheat sheets, tool lists, lookup tables

def detect_doc_type(text: str, filename: str) -> DocType:
    POLICY_SIGNALS    = ["red line", "never", "forbidden", "hard constraint", "non-negotiable"]
    PERSONA_SIGNALS   = ["you are", "your vibe", "who you are", "core truths", "soul"]
    REFERENCE_SIGNALS = ["## examples", "```", "cheat sheet", "quick reference", "lookup"]

Per-type scoring: skip HERM-2/3 for REFERENCE docs, reduce vagueness penalty for PERSONA, treat security negatives in POLICY as features.

Evidence

Derived from CS-001/CS-002 self-audit (AGENTS.md, SOUL.md, TOOLS.md), CS-003 (NemoClaw SKILL.md, 141 HN pts), CS-004 (Microsoft AgentAsJudge).

Estimated effort: Medium (1-2 days). Auto-detection heuristics, CLI flag, per-type weight tables.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions