Use this prompt to repeat the same workflow for any Java topic, such as concurrency, generics, collections, streams, serialization, exceptions, records, pattern matching, or performance.

Replace the placeholders before running it:

• <TOPIC>: the chapter topic, for example Concurrency or Generics
• <JDK_BASELINE>: the oldest supported JDK, for example JDK 13+
• <JDK_TARGET>: the target JDK, for example JDK 25
• <STYLE_REFERENCE>: optional book/article/PDF/style source to learn from
• <SOURCE_ZIP_OR_API_PATHS>: optional JDK source files or API docs to inspect
• <PROJECT_ROOT>: the Java project path where markdown, code, and PDF should be created

You are a senior Java engineer and technical book author. Your job is to create a modern Effective Java-style chapter about <TOPIC> for <JDK_BASELINE> programs targeting <JDK_TARGET>.

The goal is not to summarize APIs. The goal is to write practical book items: each item should state a design rule, explain why it matters, show broken and correct code, describe counterexamples, cite primary sources, and end with a strong summary sentence.

Work in <PROJECT_ROOT>.

• Topic: <TOPIC>
• Baseline: <JDK_BASELINE>
• Target: <JDK_TARGET>
• Style reference: <STYLE_REFERENCE>
• JDK/source references: <SOURCE_ZIP_OR_API_PATHS>
• Desired output:
  • One consolidated markdown chapter
  • A runnable Java validation class or small validation package
  • Maven or Gradle configuration updates if needed
  • A generated PDF from the final markdown
  • A short final summary of files changed and commands run

1. If a style reference is supplied, extract only style, structure, pacing, and conventions. Do not copy copyrighted prose.
2. Use primary sources for technical claims:
   • OpenJDK JEPs
   • official JDK API docs
   • local JDK src.zip
   • relevant source files under the target JDK
3. Prefer local source files over web search when available.
4. For facts that may have changed, verify against current official sources.
5. If subagents are available, use them for research:
   • one agent for item discovery
   • one agent for official source/JEP verification
   • one agent for validation-code ideas
   • parallel agents for major Java vendor and engineering-shop research
   • one aggregation agent to turn research findings into candidate item topics
6. Keep the final chapter practical. Avoid marketing language, vague recommendations, or API catalog prose.
7. The code must compile and run in the project.
8. The validation code should validate the chapter's claims, not benchmark throughput unless the item is explicitly about performance measurement.
9. Do not revert unrelated user changes in the repository.

Write in the spirit of an Effective Java item:

• Use numbered item titles with imperative advice:
  • Item 85: Prefer virtual threads for blocking I/O
  • Item 12: Prefer bounded wildcards for producer-consumer APIs
• Start with the problem, not the API.
• Show an anti-pattern before the corrected form when useful.
• Include short, compilable or nearly compilable code examples.
• Use bold rule sentences inside each item.
• Explain why the rule exists, not just what the rule says.
• Include counterpoints and legitimate exceptions.
• End each item with In summary, ...
• Cite sources at the end of each item.
• Use concrete examples:
  • CPU-bound work can be prime counting.
  • context propagation can use request IDs.
  • cancellation can use InterruptedException.
  • generics can use producer/consumer collections.

Read the project structure and build system.

Check:

• pom.xml, build.gradle, or equivalent
• Java source layout
• existing package names
• current JDK configuration
• whether preview features are already enabled

If the target JDK requires preview APIs, update build/run configuration deliberately and document that choice.

If <STYLE_REFERENCE> is supplied:

• Read it.
• Extract structure, tone, item format, code-example style, source-citation style, and summary style.
• Save the extracted style guide as a separate markdown file, for example: EffectiveJavaStyleGuide.md
• Do not preserve or reproduce copyrighted passages.

Create an initial item roster for <TOPIC>.

For each candidate item, identify:

• the rule
• target JDK feature or language behavior
• why it matters
• common anti-pattern
• correct idiom
• counterexample
• primary source
• possible validation code

Use subagents if available:

• Ask one research agent for the canonical item list.
• Ask another research agent for 5 additional modern items not in the initial list.
• Ask another research agent to verify source links, JEPs, and JDK source paths.

Prefer <JDK_TARGET> APIs and behavior, but note when an API was introduced in an earlier JDK.

In addition to JEPs and JDK API docs, research how serious Java shops explain, debug, tune, or operationalize <TOPIC>. Use this research to discover article topics, real production concerns, edge cases, and terminology that may not be obvious from the API alone.

Prioritize sources from:

• Oracle Java Platform Group and official Java blogs
• OpenJDK mailing lists, JEPs, and project pages
• Azul engineering blogs and performance notes
• Red Hat Java, Quarkus, Mandrel, and OpenJDK engineering posts
• IBM Semeru, OpenJ9, and Java performance documentation
• Google engineering publications and Android/Java guidance where relevant
• Netflix, LinkedIn, Uber, Meta, Amazon, Microsoft, JetBrains, Spring, and other well-known Java-heavy engineering organizations when they have primary or high-quality technical posts

Use these sources as research inputs, not as prose to copy. Extract:

• recurring pain points
• migration warnings
• performance traps
• observability techniques
• operational checklists
• API misuse patterns
• testing strategies
• production incident themes
• terminology that practitioners use

For every vendor/shop source used, record:

• source name
• URL or local reference
• publication date if available
• the claim or topic it supports
• whether the source is primary, vendor guidance, engineering blog, or secondary commentary

When subagents are available, run research in parallel instead of serially. Assign each agent a clear slice and ask for citations plus candidate item topics.

Suggested split:

• Agent 1: OpenJDK, JEPs, and official JDK docs for <TOPIC>
• Agent 2: Oracle and Java Platform Group material
• Agent 3: Azul and JVM performance/runtime material
• Agent 4: Red Hat, Quarkus, Mandrel, and OpenJDK engineering material
• Agent 5: IBM Semeru/OpenJ9 material
• Agent 6: Google and large-scale Java engineering material
• Agent 7: validation-code ideas and deterministic examples

After the agents return, aggregate their findings into:

• a ranked list of candidate Effective Java-style items
• five additional modern items not already in the list
• source-backed article topics
• rejected topics with reasons
• claims that need verification against primary sources

Do not include an item merely because a vendor blog mentions it. Promote it to an item only if it can be stated as durable Java design advice and verified against primary sources or executable code.

Use <SOURCE_ZIP_OR_API_PATHS> when supplied.

For each relevant JDK source file:

• confirm class purpose
• confirm @since
• inspect important methods
• inspect source comments where they define behavior
• cite exact local source paths where useful

Example source citation format:

Sources: [JEP 444](https://openjdk.org/jeps/444),
`/path/to/src.zip!/java.base/java/lang/Thread.java:102`.

Create one consolidated markdown file:

Modern_Effective_Java_<TOPIC>.md

The chapter should include:

• short introduction
• all numbered items
• code examples
• counterpoints
• source citations
• companion validation note
• final validation matrix

Each item should follow this shape:

## Item N: Imperative item title

Problem framing.

```java
// Broken or anti-pattern example

Explanation.

// Correct or modern example

Bold rule sentence.

Nuance, exceptions, and design boundaries.

In summary, repeat the rule in a memorable form.

Sources: ...

### 6. Add More Detail Where Code Teaches Better Than Prose

After writing validation code, revisit the chapter and update it based on what
the code proves.

For every item, ask:

- Did the code reveal a clearer example?
- Did the code expose a missing definition?
- Did the code show a better boundary or exception?
- Should the item include a validation note?
- Should the companion validation matrix be updated?

For example, if the topic is concurrency:

- Define `carrier`.
- Define `mount` and `unmount`.
- Define `pin` and `pinning`.
- Explain that pinning is a carrier-availability issue, not deadlock or CPU
  speed.
- Show a concrete virtual-thread example such as `request-17` mounted on
  `ForkJoinPool-1-worker-3`.

### 7. Generate Validation Code

Create runnable validation code under the existing Java source tree.

For example:

```text
src/main/java/<project/package>/<topic>/<Topic>TheoryValidation.java

The validation class should:

• have one method per item
• print Item N PASS for each item
• throw AssertionError on failure
• avoid flaky timing where possible
• keep workloads small
• validate behavior, ownership, API shape, cancellation, scoping, or source claims
• include helper methods only when they clarify the example

For concurrency, examples may include:

• virtual threads for blocking waits
• fixed platform-thread pool for prime counting
• executor close with try-with-resources
• structured subtasks
• ScopedValue inheritance through StructuredTaskScope
• ReentrantLock timed and interruptible acquisition
• JFR RecordingStream
• Future.state(), resultNow(), and exceptionNow()
• Duration and threadId()
• splittable RandomGenerator
• StableValue.supplier
• deliberate thread factories
• explicit CompletableFuture executors
• interruption propagation
• private identity monitor locking

For generics, examples may include:

• invariant List<T> behavior
• producer ? extends T
• consumer ? super T
• generic helper methods for wildcard capture
• heap pollution detection
• @SafeVarargs
• type-safe heterogeneous containers
• generic builders
• records and sealed types with generics
• pattern matching boundaries with erased types

Run the project compile command.

Run the validation class.

If Maven:

mvn -q compile
mvn -q exec:exec -Dexec.mainClass=<fully.qualified.ValidationClass>

If Gradle:

./gradlew compileJava
./gradlew run --args='<args-if-needed>'

If preview APIs are used, configure the build and runtime with --enable-preview.

Do not claim validation passed unless the commands actually pass.

After the markdown is complete, generate a PDF.

Use available local tooling, for example:

• pandoc, if installed
• typst, if a Typst conversion path exists
• Markdown-to-HTML plus headless Chrome print-to-PDF

Expected output:

Modern_Effective_Java_<TOPIC>.pdf

Verify the PDF exists and report page count if tooling can provide it.

Keep the final response concise.

Include:

• markdown file path
• validation code path
• PDF file path
• commands run
• whether validation passed
• any limitations, such as preview APIs or missing tooling

Use absolute file links when referencing files.

Before finishing, verify:

• The chapter is one consolidated markdown file.
• Item numbering is continuous.
• Every item has a clear rule.
• Every item has at least one concrete example.
• Every item has a counterpoint or boundary.
• Every item cites primary sources.
• The validation code has one method per item.
• The validation code compiles.
• The validation code runs.
• The PDF was generated from the latest markdown.
• Unrelated repository changes were not reverted.

Use these after the first draft:

Review the chapter against the validation code. For every item, update the
document wherever the code gives a clearer example, missing definition, or
better boundary.

Add five more modern items for this topic that are not already in the chapter.
Use only primary sources and include validation-code ideas for each.

Create or update the runnable validation class so every item has a small,
deterministic check. Then run the build and validation command.

Generate a PDF from the final markdown and verify the output file.