Mystify7777 / Mystify7777/devlens

Docs/ADR: reconcile Network outcome and severity decisions

Open
#23 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

architecture documentation
Dominant language
TypeScript
Stars
0
Forks
0
PR merge metrics
No merged PRs in 30d

Description

Goal

Reconcile the Network documentation with decisions that are already implemented and tested, without rewriting the historical research record.

Audit finding

The current Network implementation has a concrete six-value NetworkOutcome contract and a concrete outcome-to-severity mapping. packages/network/src/types.ts explicitly describes the outcome as locked and says severity mapping is already resolved in the capture layer.

However, docs/adr/0010-network-plugin.md still lists both exact outcome enum values and severity mapping per outcome as open questions. The underlying research document also still describes those exact questions as undecided.

This is now documentation drift: the code has crossed the decision boundary, but the ADR still tells future contributors that the boundary is open.

Required work

Audit the actual classifier and tests and reconstruct the implemented contract exactly, including:

  • all NetworkOutcome values,
  • HTTP status classification,
  • status === 0 / opaque behavior,
  • aborted vs timeout vs network-error distinction,
  • severity for each outcome/status class,
  • any fallback classification behavior,
  • Fetch/XHR consistency.

Then determine which document should carry the accepted decision and use an ADR amendment where appropriate. Preserve the original research and historical ADR text rather than silently rewriting it.

The final documentation should clearly distinguish:

  1. what was originally researched,
  2. what was subsequently decided and implemented,
  3. what remains genuinely open in Network.

Constraints

  • Documentation/ADR work only unless the audit finds a genuine implementation contradiction.
  • Do not change the classifier merely to make documentation easier.
  • Do not reopen URL identity, endpoint grouping, response metadata, redirect behavior, or uninstall semantics. Those remain separate concerns.
  • Do not alter Core, Panel, or event schema behavior.

Verification

Validate the documented contract against the classifier's focused tests and current type definitions. Run pnpm format:check and git diff --check; broader verification is only needed if source code unexpectedly changes.

Keep the final diff focused and historically honest.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with packages/network/src/types.ts, then inspect the Network classifier and its focused tests to reconstruct the implemented contract. Compare those findings with docs/adr/0010-network-plugin.md and the underlying research document, preserving historical text while documenting decided versus open questions. Validate the result with the focused tests, pnpm format:check, and git diff --check.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
72/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.