Skip to content

methodology.md

Latest commit

 

History

History
77 lines (55 loc) · 3.79 KB

methodology.md

File metadata and controls

77 lines (55 loc) · 3.79 KB
Raw

Methodology

Web App Completeness evaluates whether a coherent user workflow exists, not whether a screen contains a predetermined number of controls.

Rule authority

Authority Meaning
standard A normative accessibility, security, or platform requirement
official-pattern Conditional guidance from an official design system or framework
project-heuristic A testable product or correctness rule maintained by this repository

Rule strength is independent of authority:

  • must: violating the applicable rule creates a standards, security, data-integrity, or reachability defect.
  • must-decide: the capability must be classified, but inclusion is contextual.
  • should: prefer the rule unless project evidence supports an exception.
  • may: optional enhancement with a stated trigger.

Each rule defines applies_when, skip_when, explicit exceptions, source IDs, verification instructions, a verification date, and the skills that consume it.

Capability decisions

Planning and build contracts use:

State Meaning
present The capability already exists and its path is evidenced
include It belongs in the approved implementation scope
defer It is applicable but intentionally postponed with a reason
not-applicable A concrete option raised by the request is excluded, or a documented exception prevents a likely scope mistake
needs-decision A material product choice remains unresolved

Rules whose triggers have no positive request, domain, or repository evidence stay out of the contract. Do not inventory every unmet trigger as not-applicable. completeness-build cannot mutate the application while any needs-decision remains.

Audits use covered, confirmed-gap, and manual-review. A source inspection can confirm missing code paths and dataset truncation. Claims about focus behavior, responsive layout, or rendered feedback require browser evidence; without it they stay manual-review.

Findings

Every reported gap carries:

  • stable rule ID and capability area
  • severity: critical, high, medium, or low
  • confidence: high, medium, or low
  • file-and-line evidence or an explicit manual-review reason
  • current behavior and user impact
  • authority and strength
  • bounded recommendation and verification method

The evidence model defines canonical IDs for recurring root defects such as filtering a truncated dataset, error-as-empty handling, a missing edit path, raw-ID relationship entry, unsafe deletion, and unjustified cross-module drift. Agents reuse those exact IDs when the definition matches; genuinely different defects receive a deterministic semantic F-<AREA>-<DEFECT> ID.

Severity reflects impact, not visual prominence:

  • critical: security bypass, likely data loss, or an inaccessible core workflow
  • high: users cannot complete or reach a common operational task
  • medium: substantial friction, ambiguity, or weak recovery
  • low: localized consistency or polish issue with a working alternative

Avoiding checklist cargo cults

The catalog asks whether collection controls, bulk actions, undo, confirmation, imports, exports, URL state, and audit history are applicable. It does not require them everywhere.

Examples:

  • A five-item fixed reference list can be complete without search or pagination.
  • Pagination is one way to make all records reachable; cursor navigation, load-more, virtualization, or a complete short list can also work.
  • Undo and confirmation are alternative safeguards in many contexts.
  • Soft deletion can conflict with a genuine erasure requirement.

The invariant displayed rows = paginate(sort(filter(complete reachable dataset))) is different: filtering or sorting an already truncated subset while making other records unreachable is deterministically incorrect.