New Class

Before writing any code

Read the following files in full:

1. .dev/WORKFLOW.md — the required order of operations; follow it strictly
2. .dev/standards/ — coding standards for the project's language
3. .dev/design/ARCHITECTURE.md — existing design decisions and rationale
4. .dev/backlog/BACKLOG.md — pending tasks; check if this class is already listed

Procedure

Follow the order defined in .dev/WORKFLOW.md:

1. Update ARCHITECTURE.md
2. Update BACKLOG.md
3. Write production code (then run static-analysis)
4. Write tests (black-box first, then white-box)
5. Update README.md (run update-readme)

1. Clarify the design (before coding)

Ask the user — or infer from context — the following:

• What is the core data structure and its invariant?
• Does it implement an existing interface? If so, which abstract base class should it extend?
• Is a thread-safe variant needed alongside an unsynchronized one?
• What are the key operations and their expected complexity?
• Are there configurable strategies or behaviours?
• What design alternatives were considered and rejected? (for ARCHITECTURE.md)

Do not proceed to code until the design is clear.

2. Generate the source file

Required structure (in order):

1. File header — as defined in the project's coding standards (license, version, etc.)
2. Package / module statement
3. Import / dependency statements — explicit, sorted, no wildcards
4. Class documentation — describe the data structure, its invariant, complexity, thread-safety, and any non-obvious contracts
5. Class declaration — extends the appropriate base class if applicable
6. Body — in order: static fields, instance fields, constructors, methods (grouped by functionality, with section separators)

3. Generate the test classes

Black-box test

• Tests based solely on the public contract and documentation
• No knowledge of internal implementation
• Cover: nominal case, boundary cases, error cases (expected exceptions)
• Must be writable without reading the source code

White-box test

• Tests targeting technically risky internal areas
• Each test must have a comment explaining why it targets that specific point (e.g. hash collision, resize boundary, lock ordering)
• Cover: internal structure consistency, algorithmic edge cases, concurrent modification if applicable

4. Run static analysis

After generating the source file, apply the static-analysis skill to the produced code. Report all findings before proceeding.

5. Update ARCHITECTURE.md

Add a new section for the class with:

• The key design decisions made
• Alternatives considered and reasons for rejection
• Any invariants that future contributors must preserve

6. Update BACKLOG.md

Add a new section for the class with:

• [ ] Create black-box test (if not yet written)
• [ ] Create white-box test (if not yet written)
• Any known limitations or future tasks discovered during design
• Move completed items to ### Done under the class name

Checklist before handing off

• File header present and version matches the build file
• All imports explicit and sorted
• All public methods have documentation with parameters, return values, and exceptions
• Nullable return types handled according to project standards
• Abstract base class extended where available
• Overrides of inherited methods documented if semantics differ
• Static analysis run and findings reported
• ARCHITECTURE.md updated
• BACKLOG.md updated