ADR 0005: Unparsed Requirement Semantics
ADR 0005: Unparsed Requirement Semantics
Status: Accepted for architectural direction.
Date: 2026-05-11.
Context
Waterloo and Kuali requirement fields include structured-looking rendered HTML and natural-language fragments.
The scraper parser will recognize many common all-of, any-of, choose-count, course-list, grade, progress, and subject-pool patterns.
Some requirement fragments will remain ambiguous.
Some requirement fragments will require manual patches.
Some requirement fragments may never be worth fully parsing.
The backend will answer student-facing queries.
The backend must not treat unparsed fragments as satisfied.
The backend must not treat unparsed fragments as irrelevant.
The backend must not force every query into true or false.
The frontend must be able to explain uncertainty.
Decision
Unparsed requirements are first-class records.
Unparsed requirements must be stored in parsed outputs.
Unparsed requirements must be stored in the runtime index.
Unparsed requirements must be linked to source references.
Unparsed requirements must be visible to validators.
Unparsed requirements must be visible to backend query logic.
Unparsed requirements must be visible to frontend explanations when relevant.
Backend requirement evaluation must use multi-state results.
The core result states are:
satisfiednot_satisfiedpartialunknownconflictnot_applicable
If an otherwise satisfied requirement group contains an applicable unparsed child, the result should usually be unknown.
If an unparsed child is inside an any-of group with a different satisfied child, the group may be satisfied.
If an unparsed child is inside an any-of group and no parsed child is satisfied, the group may be unknown.
If an unparsed child is inside an all-of group, the group cannot be fully satisfied unless policy explicitly marks the child as non-applicable.
If an unparsed requirement belongs to a field that is advisory-only, it may be excluded from strict solver evaluation with an explicit reason.
The parser should classify requirement source fields by evaluation role.
The backend should preserve source text in explanation responses.
The backend should expose a concise uncertainty summary.
Evaluation Roles
Evaluation role enrollment means course add eligibility.
Evaluation role credential_completion means degree, major, minor, option, or specialization satisfaction.
Evaluation role declaration means eligibility to declare a credential.
Evaluation role advisory means useful information not directly evaluated.
Evaluation role unknown means parser or source classification is incomplete.
Unparsed requirements in unknown evaluation roles should remain conservative.
Unparsed requirements in advisory roles should remain visible but may not block solver answers.
Unparsed requirements in credential_completion roles should affect credential progress answers.
Unparsed requirements in enrollment roles should affect unlock answers.
Query Response Policy
Every query response should include a top-level status.
Every query response should include a confidence or certainty summary.
Every query response should include blocking parsed requirements.
Every query response should include relevant unparsed requirements.
Every query response should include source references when available.
Every query response should distinguish not_satisfied from unknown.
Every query response should distinguish unknown from conflict.
Every query response should avoid saying a credential is complete when relevant requirements are unknown.
Every query response should avoid saying a course is unlocked when relevant enrollment requirements are unknown.
Every query response may say a requirement is partially satisfied.
Every query response may include recommended review text.
Alternatives Considered
Alternative 1: Treat Unparsed as False
The backend could treat every unparsed requirement as unsatisfied.
This is conservative in one direction.
However, it would over-block pathways.
It would make the app feel wrong when unknown text is advisory or irrelevant.
This alternative is rejected.
Alternative 2: Treat Unparsed as True
The backend could ignore unparsed requirements.
This maximizes optimistic usability.
However, it creates false authority.
It can claim courses are unlocked or credentials are complete when source rules were not understood.
This alternative is rejected.
Alternative 3: Hide Unparsed from Users
The system could log unparsed fragments but not show them.
This keeps UI cleaner.
However, it hides exactly the uncertainty users need when planning.
This alternative is rejected.
Consequences
Backend query types must support multi-state evaluation.
The frontend must design for uncertainty.
The index schema must include unparsed requirement tables.
The parser must classify source fields by evaluation role.
Validation reports become part of product trust.
Some early answers will be less decisive.
Less decisiveness is preferable to false precision.
Follow-Up
Define exact result aggregation rules in backend query specs.
Define frontend language for unknown requirements.
Define validation thresholds for unparsed requirements in release gate ADR.
Define patch governance for reducing high-impact unknowns.