view release on metacpan or  search on metacpan

doc/internal-operating-checklist.md  view on Meta::CPAN

# Internal Operating Checklist

Use this checklist at the start, during, and end of every meaningful change in
Developer Dashboard.

It is a compact execution guide distilled from:

- `ELLEN.md`
- `AGENTS.override.md`
- `agents.md`
- `SECURITY.md`
- `SECURITY_CHECKS.md`
- `README.md`
- `SOFTWARE_SPEC.md`
- `doc/testing.md`
- `doc/integration-test-plan.md`
- `doc/windows-testing.md`
- `doc/update-and-release.md`
- `MISTAKE.md`
- `FIXED_BUGS.md`

If any detail here appears to conflict with those files, the higher-priority
source files win.

## 1. Operating Mindset

1. Follow `ELLEN.md` first.
2. Do not stop at symptoms, guesses, wrappers, or partial evidence.
3. Verify suspicious output directly.
4. Use the full system before claiming a blocker.
5. Treat a fix as incomplete until the result is verified and the lesson is captured.
6. Do not wait for a `yes` when the next action is already justified by the task, the current findings, or the repo rules.

## 2. Before Touching Code

1. Read the governing docs and the task-specific docs fully before making assumptions.
2. Confirm the work stays out of `OLD_CODE`.
3. Remove any legacy/company-specific logic from the solution space:
   `Companies House`, `EWF`, `XMLGW`, `CHIPS`, `Tuxedo`, `CHS`, `Grover`,
   `CIDEV`, `PBS`, credentials, and sensitive-data flows do not belong in core.
4. Identify the runtime surfaces affected:
   CLI, browser, collectors, auth, routing, packaging, Windows, Docker,
   layering, prompt, or release workflow.
5. Review related entries in `MISTAKE.md` and `FIXED_BUGS.md` before implementing.

## 3. Design And Implementation Rules

1. Follow TDD.
2. Add or update tests under `t/` first where practical.
3. Keep `dashboard` thin and lazy.
4. Do not bloat `bin/dashboard` with reusable behavior or heavy built-in bodies.
5. Treat `DD-OOP-LAYERS` as a cross-runtime contract, not a convenience feature.
6. Never suppress errors.
7. Treat warnings as errors.
8. Do not hide broken behavior behind fallback logic unless the fallback is explicit, documented, and tested.
9. Make logs visible and explicit.
10. Use:
   - `JSON::XS`
   - `LWP::UserAgent`
   - `Capture::Tiny`
11. Never use:
   - `LWP::Simple`
   - `HTTP::Tiny`
   - `JSON::PP`
   - `capture_merged`
12. Use the required `Capture::Tiny` pattern:

```perl
use Capture::Tiny qw(capture);

my ($stdout, $stderr, $exit) = capture {
   system($command);
};
```

13. Every function must document:
   - what it does
   - input arguments
   - expected output
14. Follow the CLI output contract:
   - operator-facing inventory and mutation commands default to human-readable summaries, preferably tables
   - `-o json` returns the full machine payload, not a truncated summary
   - shell-plumbing commands may keep direct raw output when a summary table would break their contract

## 4. Delivery Model

The project uses all of these at once:

- `TDD` for implementation discipline
- behavior-driven documentation and spec language for user-visible contracts
- acceptance-driven verification for installed-runtime and cross-platform proof

Use that model like this:

1. define the expected behavior from docs, tests, or a bug report
2. write or update the failing test first where practical
3. implement the smallest coherent fix
4. rerun the fast suite
5. run the environment-specific acceptance gates required by the change
6. update docs and release metadata in the same change