java-streams-eval-capture

Java Streams Eval Capture

Goal

When a Symphony for Trello change provides a reusable stream, collector, direct result-producing collection API, or character-predicate equivalence lesson, preserve the teaching example for the Java Streams skill. This includes cases where a direct owning API is better than a stream or where a useful stream-equivalence pattern appears inside another fluent API. Create or update an issue in martinfrancois/java-streams-skill that stands on its own: it must include the relevant code before the refactor, the prompt or review request that triggered the change, the intermediate or rejected implementation when one exists, the final preferred code, and why the final code is better.

When the stream improvement is prompted by a reviewer or user after Codex introduced the weaker stream shape, also capture the earlier prompt that caused Codex to write that shape. The eval issue must make the trigger failure explicit: the Streams skill should have activated during the original implementation prompt, not only during the later stream-refactor request.

When a later request reveals only that activation or eval capture was missed, even though the implementation was already preferred, capture both prompts and state that no code correction was needed. The eval must reward recognizing and capturing the reusable lesson without inventing a defect.

When a stream refactor is later found to be non-equivalent, over-allocated, over-abstracted, or worse than the original code, capture the full correction chain. Include the original code, the prompt that produced the weaker stream code, the weaker code, the later correction/revert prompt, and the final code. The eval must teach the skill to preserve behavior by default, and to call out any mutability, ordering, laziness, parser, exception, allocation, or side-effect change explicitly before recommending it.

When To Use

Use this skill whenever you:

• refactor Java code to use streams more clearly, lazily, or safely;
• replace a loop with a stream or a stream with a clearer stream shape;
• replace or remove a stream with a stronger direct collection API where the choice or equivalence boundary is reusable;
• simplify result-producing collection work inside Optional.map(...) or a similar fluent mapping when the collection transformation itself presents a reusable lesson, even when the final code contains no .stream();
• replace a loop or character scan with a primitive stream and a match terminal when empty-input, UTF-16, or code-point semantics matter;
• replace an identity string reduction such as .reduce("", String::concat) with Collectors.joining(), even when a related delimiter reduction was already captured;
• fix stream short-circuiting, ordering, allocation, collector, Optional, or pipeline readability problems;
• accept a user-provided streams refactor;
• correct a streams refactor after review feedback;
• revert or repair a stream refactor because it changed behavior, allocation, mutability, ordering, laziness, parser semantics, or side-effect boundaries.

Do not use this skill for unrelated Java edits that merely happen to touch a line containing .stream(), a routine collection factory/copy, or character indexing without a reusable stream/direct-API choice or behavior-equivalence lesson. When only collection work inside an Optional mapping changes, use this skill without also triggering Optionals capture unless the Optional design or absence behavior changes too.

Workflow

For a broad Java, API, or refactoring audit, enumerate every implemented collection, stream, and character-transformation change that presents a reusable choice or equivalence lesson before capture. Create or update one issue for each distinct reusable equivalence boundary. Combine occurrences only when the same inputs, outputs, and behavior constraints make them one pattern; do not stop after capturing only the most visibly stream-shaped change. Do not combine cases solely because they use the same destination API. Capture identity concatenation such as .reduce("", String::concat) separately from a conditional delimiter reducer: verify null elements, empty sources, empty elements, and encounter order for the identity reduction, and verify delimiter placement and sentinel collisions separately for the delimiter reduction.

1. Capture the pre-refactor code from Git before editing when possible:

   git show HEAD:path/to/File.java
   

   If work is already in progress, use the nearest available commit, patch, or review comment that shows the code before the streams change.

2. Capture the prompt or review instruction that caused the streams refactor. Quote only the relevant requirements.

3. If the weaker stream code was agent-produced earlier in the same transcript or PR, inspect the transcript, commit history, review thread, or issue prompt to recover:

   • the code before that earlier prompt ran;
   • the earlier prompt that should have triggered the Streams skill;
   • the agent-produced stream code that later needed correction.

   If the exact earlier prompt is unavailable, state that explicitly and use the nearest recoverable prompt or commit message. Do not stop at the later "please refactor/use streams" prompt when the useful eval is a missed-trigger case.

4. Capture the intermediate implementation when there was one. This is the code that was produced before the better version, or the code the user/reviewer corrected.

5. If the stream refactor changed behavior or was later judged worse, capture the correction prompt and explain the equivalence failure. Include both:

   • the behavior-preserving alternative the skill should have suggested first;
   • any behavior-changing alternative only when the available context proves the behavior change is safe or desirable.

   If the context is insufficient to prove that a behavior-changing refactor is safe, the desired eval behavior should reward asking for confirmation or choosing the behavior-preserving shape.

6. Capture the final preferred code.

7. Search all open and closed Java Streams skill issues for the same pattern:

   gh issue list --repo martinfrancois/java-streams-skill --state all --search '<pattern keywords>'
   

   Update an existing matching issue instead of creating a duplicate. A matching closed issue also prevents a duplicate; record why it already owns the lesson, and reopen it only when the new occurrence proves that required work remains. If the same pattern appears in a different code location, add a comment to the existing issue with that occurrence's relevant before code, triggering prompt, intermediate code when available, final code, and why the same eval should cover it. Do not skip the capture merely because the issue already exists for another file.

8. Create or update the issue with a self-contained body. Do not include a "Repository context" section, and do not require the reader to open the source repository or pull request to understand the eval.

   gh issue create \
     --repo martinfrancois/java-streams-skill \
     --title 'Add eval for <stream pattern>' \
     --body-file /tmp/java-streams-eval-issue.md
   

9. Add or update a temporary override in docs/agents/java-style.md or the narrowest relevant agent-doc page for every eval issue that captures bad, missing, or unreliable Streams-skill behavior observed in Symphony for Trello. Link the issue from the override. The override must say to check the linked issue state at most once per turn before applying it, and to remove the override when the linked issue is closed. Do not leave agents relying only on the future upstream skill fix when the current repo has already observed the bad behavior. If an existing temporary override already covers the issue, update that override or record in the eval comment which override covers it instead of adding a duplicate.

Issue Body Shape

Use this structure and adapt the wording to the stream pattern:

## Problem

Describe the Java Streams lesson the skill should learn. State why this is
eval-worthy and not just generic style.

## Code before the prompt was executed

Explain the old behavior, then include the smallest relevant code block.

```java
// pre-prompt code
```

## Prompt that caused the implementation

List the relevant user, review, or product requirements that caused the
stream-relevant pattern to be implemented. If this is a missed-trigger case,
this is the original implementation prompt, not the later capture request. Do
not call already-preferred code weak merely because activation or capture was
missed.

## Later prompt that exposed the issue

Use this section when a reviewer or user later asked to use the Streams skill or
corrected the implementation. Explain that the later prompt is useful context
but should not be the only eval trigger.

## Prompt-produced or reviewed code

Show the implementation that should have triggered the skill. When an
intermediate or rejected implementation exists, explain its concrete streams,
readability, performance, or behavior-equivalence problem. When the code was
already preferred and only activation or capture failed, say so explicitly.

```java
// prompt-produced or reviewed code
```

## What the skill missed

State whether the miss was the code choice, behavior analysis, skill activation,
eval capture, or some combination. Explain a code defect only when one exists.
For short-circuiting cases, state whether work happens inside or before the lazy
stream pipeline.

## Behavior-equivalence analysis

Use this section when the refactor changes or might change mutability, ordering,
allocation, laziness, parser semantics, exception behavior, or side-effect
boundaries. State whether the behavior change is safe, unsafe, or not provable
from local context.

---

*Content truncated.*