Mystify7777 / Mystify7777/devlens
Docs/ADR: reconcile Network outcome and severity decisions
Nobody has claimed this yet.
- 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
NetworkOutcomevalues, - 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:
- what was originally researched,
- what was subsequently decided and implemented,
- 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
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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