This repository was archived by the owner on Dec 12, 2025. It is now read-only.
AI-Scaffolded Topic pages for Core Archetype#68
Open
GreenIcicle wants to merge 4 commits intoZuehlke:mainfrom
Open
AI-Scaffolded Topic pages for Core Archetype#68GreenIcicle wants to merge 4 commits intoZuehlke:mainfrom
GreenIcicle wants to merge 4 commits intoZuehlke:mainfrom
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
This PR scaffolds content for 40+ topic pages using AI generation to address missing or stub content in the Core Archetype learning pathway. The changes add comprehensive YAML frontmatter with learning resources, descriptions, and cross-references, along with AI-generated content marked for community review. Additionally, the PR introduces documentation about the AI scaffolding process in README.md and updates Copilot instructions.
Key Changes
- AI-generated topic content: Added structured YAML frontmatter and descriptive content to 40+ topic pages with learning resources from reputable sources (O'Reilly books, official documentation, Martin Fowler articles)
- Documentation updates: Added "AI based scaffolding" section to README.md explaining the AI content generation process and guidelines
- Minor formatting fixes: Updated docs/design-principles.md and docs/data-architecture.md with consistent spacing
Reviewed changes
Copilot reviewed 53 out of 53 changed files in this pull request and generated 11 comments.
Show a summary per file
| File | Description |
|---|---|
| src/topics/user-stories.md | Added full YAML frontmatter with 3 learning resources, cross-references, and AI-generated description |
| src/topics/threat-modelling.md | Added YAML frontmatter with threat modeling resources (STRIDE, OWASP, Adam Shostack's book) |
| src/topics/the-test-pyramid.md | Critical bug: YAML frontmatter delimiter corrupted ("d---" instead of "---") |
| src/topics/technical-documentation-writing.md | Added documentation-focused resources including Google Technical Writing course |
| src/topics/technical-architecture-intro.md | Added architecture fundamentals resources and cross-references |
| src/topics/systems-and-complexity-sciences.md | Added systems thinking resources including Donella Meadows' "Thinking in Systems" |
| src/topics/styleguides-and-linting.md | Added linting and style guide resources (Google Style Guides, EditorConfig) |
| src/topics/solid.md | Added SOLID principles resources with Gang of Four cross-reference |
| src/topics/software-design-modelling-and-diagramming-languages.md | Added UML and C4 model resources; grammar error in description |
| src/topics/shifting-left-security.md | Added security-focused resources including OWASP and threat modeling |
| src/topics/secure-coding-practices.md | Added OWASP Top 10 and security-focused book resources |
| src/topics/scrum.md | Changed title from "SCRUM" to "Scrum" (correct capitalization), added Scrum resources |
| src/topics/root-cause-analysis.md | Added RCA methodology resources including SRE book |
| src/topics/rest-design.md | Added RESTful API design resources |
| src/topics/relational-databases.md | Added SQL and database design resources |
| src/topics/profiling-and-performance-tuning.md | Added performance resources; questionable "Practical Vim" inclusion |
| src/topics/performance-and-scalability.md | Added performance optimization resources |
| src/topics/pair-programming.md | Replaced existing content with AI-generated version (violates stated principle) |
| src/topics/os-shell-basics.md | Added shell scripting and command-line resources |
| src/topics/nosql-databases.md | Added NoSQL database resources (MongoDB, NoSQL Distilled) |
| src/topics/non-functional-requirements.md | Added NFR and quality attributes resources |
| src/topics/multiple-languages-and-paradigms.md | Added polyglot programming resources |
| src/topics/monitoring-and-observability.md | Added observability resources (Prometheus, SRE book) |
| src/topics/mentoring-and-coaching.md | Added coaching and mentoring resources |
| src/topics/legacy-systems.md | Replaced existing curated resources with AI-generated generic ones |
| src/topics/internet-protocols.md | Added networking and protocol resources |
| src/topics/intellectual-property-laws-and-ethical-hacking.md | Added IP law and ethical hacking resources |
| src/topics/integrated-component-tests.md | Changed Martin Fowler URL from microservice-testing to testing-strategies |
| src/topics/general-api-design-and-security-principles.md | Added API design and security resources |
| src/topics/gang-of-four-design-patterns.md | Added GoF patterns resources |
| src/topics/facilitating-agile.md | Added Agile facilitation resources |
| src/topics/enterprise-design-patterns.md | Added enterprise patterns resources |
| src/topics/effective-collaboration.md | Added collaboration and team dynamics resources |
| src/topics/domain-driven-design.md | Changed title from "Domain Driven Design" to "Domain-Driven Design", added DDD resources |
| src/topics/distributed-systems-theory-and-practices.md | Added distributed systems resources (CAP theorem, Kleppmann's book) |
| src/topics/devops-mindset.md | Added DevOps culture resources (Phoenix Project, Accelerate) |
| src/topics/debugging.md | Added debugging resources and techniques |
| src/topics/data-structures.md | Added algorithms and data structures resources |
| src/topics/data-modeling-and-databases.md | Added data modeling resources |
| src/topics/continuous-integration.md | Added CI/CD resources (GitHub Actions, trunk-based development) |
| src/topics/continuous-delivery.md | Added CD resources including Jez Humble's foundational book |
| src/topics/containers-and-orchestration.md | Added Docker and Kubernetes resources |
| src/topics/component-architectures.md | Added component architecture resources |
| src/topics/cloud-computing.md | Added cloud computing resources (AWS Well-Architected Framework) |
| src/topics/clean-code-and-refactoring.md | Added Clean Code and Refactoring resources |
| src/topics/building-for-scale.md | Added scalability resources |
| src/topics/building-evolutionary-architectures.md | Added evolutionary architecture resources |
| src/topics/automated-end-to-end-system-testing.md | Added E2E testing resources (Selenium, Test Pyramid) |
| src/topics/advanced-programming.md | Added advanced programming resources |
| README.md | Added "AI based scaffolding" section; spelling and grammar errors present |
| docs/design-principles.md | Added blank lines for consistent formatting |
| docs/data-architecture.md | Added blank lines for consistent formatting |
| .github/copilot-instructions.md | Added references to design-principles.md and data-architecture.md |
| --- | ||
| title: Software Design, Modelling, and Diagramming Languages | ||
| description: >- | ||
| Communicating design requires shared languages and diagrams: UML, C4 model, domain models, flowcharts. This topic covers when and how to use diagrams, tools, and recognizing that design documents have costs—too many become unmaintained; too few leaves decisions implicit. |
There was a problem hiding this comment.
Grammar error: "too few leaves" should be "too few leave" (subject-verb agreement - "few" is plural, so the verb should be "leave" not "leaves").
| - Learning resources need to come from sources widely accepted in expert communities | ||
| - Original documentation is preferrable | ||
| - Youtube videos from widely accepted channels with a long history of reliable information are acceptable | ||
| - Freely accessible ressources are preferred to paid-for offers |
There was a problem hiding this comment.
Spelling error: "ressources" should be "resources".
Suggested change
| - Freely accessible ressources are preferred to paid-for offers | |
| - Freely accessible resources are preferred to paid-for offers |
Comment on lines
1
to
+33
| --- | ||
| title: Pair Programming | ||
| description: >- | ||
| Pair programming is two developers working together at one computer. Studies show it catches defects early, spreads knowledge, and improves code quality. This topic covers pair programming styles (driver/navigator, ping-pong), remote pairing, when to pair, and overcoming resistance. | ||
| learning_resources: | ||
| - type: external_link | ||
| title: "Pair Programming Guide" | ||
| url: "https://www.agilealliance.org/glossary/pairing/" | ||
| description: "Introduction to pair programming practices." | ||
| - type: book | ||
| title: "The Pragmatic Programmer" | ||
| url: "https://www.oreilly.com/library/view/the-pragmatic-programmer/9780135957059/" | ||
| description: "Includes pair programming section." | ||
| author: "David Thomas" | ||
| - type: external_link | ||
| title: "Remote Pair Programming" | ||
| url: "https://tuple.app/pair-programming-guide/" | ||
| description: "Best practices for remote pairing." | ||
| cross_references: | ||
| - extreme-programming-practices | ||
| - effective-collaboration | ||
| - test-driven-development | ||
| --- | ||
|
|
||
| # Pair Programming | ||
|
|
||
| Pair programming is a collaborative software development technique in which two programmers work together at a single workstation to solve the same problem simultaneously. This approach results in higher code quality, fewer defects, improved team cohesion, and faster skill development. Although it may seem counterintuitive to managers concerned about productivity, research indicates that the slight increase in development time is often outweighed by significant reductions in debugging and maintenance costs later on. | ||
| *Generated by AI, pending community review.* | ||
|
|
||
| ## Presentation | ||
| Pair programming is two developers working together at one computer. Studies show it catches defects early, spreads knowledge, and improves code quality. This topic covers pair programming styles (driver/navigator, ping-pong), remote pairing, when to pair, and overcoming resistance. | ||
|
|
||
| <embed src="../../assets/pair-programming/zuhlke-mob-and-pair-programming-guide.pdf" type="application/pdf" width="100%" height="800px" /> | ||
| ## Learning Materials | ||
|
|
||
| {{ render_learning_resources() }} |
There was a problem hiding this comment.
This topic page appears to have had existing non-stub content (a detailed paragraph and an embedded PDF presentation), but it has been replaced with AI-generated content. The README states "The AI does not overwrite Topic pages that are already fleshed out beyond a stub," but this appears to be a violation of that principle. The original content included a detailed explanation and a presentation resource that have been removed.
|
|
||
| *Generated by AI, pending community review.* | ||
|
|
||
| Communicating design requires shared languages and diagrams: UML, C4 model, domain models, flowcharts. This topic covers when and how to use diagrams, tools, and recognizing that design documents have costs—too many become unmaintained; too few leaves decisions implicit. |
There was a problem hiding this comment.
Grammar error: "too few leaves" should be "too few leave" (subject-verb agreement - "few" is plural, so the verb should be "leave" not "leaves").
| - Provide the structure as laid out in the data architecture | ||
| - Add learning resources for all levels | ||
| - Learning resources need to come from sources widely accepted in expert communities | ||
| - Original documentation is preferrable |
There was a problem hiding this comment.
Spelling error: "preferrable" should be "preferable" (single 'r').
Suggested change
| - Original documentation is preferrable | |
| - Original documentation is preferable |
| - Original documentation is preferrable | ||
| - Youtube videos from widely accepted channels with a long history of reliable information are acceptable | ||
| - Freely accessible ressources are preferred to paid-for offers | ||
| - AI-generated pages are marked with the slug "AI-generated" in the YAML for topic pages |
There was a problem hiding this comment.
The documentation states that "AI-generated pages are marked with the slug 'AI-generated' in the YAML for topic pages," but the actual implementation marks them with the text "Generated by AI, pending community review." in the content body (not in YAML frontmatter). This inconsistency between documentation and implementation should be clarified or corrected.
Suggested change
| - AI-generated pages are marked with the slug "AI-generated" in the YAML for topic pages | |
| - AI-generated pages are marked by including the text "*Generated by AI, pending community review.*" in the content body of topic pages (not in the YAML frontmatter) |
Comment on lines
1
to
34
| --- | ||
| title: Legacy Systems | ||
| description: >- | ||
| Legacy systems are older software that's difficult to maintain or extend but critical to business. This topic covers understanding legacy code, testing without a test suite, making safe changes, and gradual refactoring strategies. Legacy systems often represent significant business value and institutional knowledge. | ||
| learning_resources: | ||
| - type: "external_link" | ||
| title: "Refactoring Legacy Code using Tiny Types and Data Oriented Programming in Java" | ||
| url: "https://software-engineering-corner.zuehlke.com/refactoring-legacy-code-using-tiny-types-and-data-oriented-programming-in-java" | ||
| - type: "external_link" | ||
| title: "Untangling Legacy Systems" | ||
| url: "https://software-engineering-corner.zuehlke.com/untangling-legacy-systems" | ||
| - type: "course" | ||
| title: "Writing Good Tests with JUnit" | ||
| url: "https://wd3.myworkday.com/zuehlke/learning/course/63dc6ad4fa471000a4cd260b776e0000?type=9882927d138b100019b6a2df1a46018b" | ||
| is_internal: true | ||
| - type: book | ||
| title: "Working Effectively with Legacy Code" | ||
| url: "https://www.oreilly.com/library/view/working-effectively-with/9780131177055/" | ||
| description: "Practical techniques for improving legacy systems." | ||
| author: "Michael Feathers" | ||
| - type: external_link | ||
| title: "Strangler Fig Pattern" | ||
| url: "https://martinfowler.com/bliki/StranglerFigApplication.html" | ||
| description: "Gradual migration from legacy systems." | ||
| - type: book | ||
| title: "Refactoring to Patterns" | ||
| url: "https://www.oreilly.com/library/view/refactoring-to-patterns/0321213351/" | ||
| description: "Improving legacy code through refactoring." | ||
| author: "Joshua Kerievsky" | ||
| cross_references: | ||
| - clean-code-and-refactoring | ||
| - root-cause-analysis | ||
| - technical-documentation-writing | ||
| --- | ||
|
|
||
| # Legacy Systems | ||
|
|
||
| *Generated by AI, pending community review.* | ||
|
|
||
| Legacy systems are older software that's difficult to maintain or extend but critical to business. This topic covers understanding legacy code, testing without a test suite, making safe changes, and gradual refactoring strategies. Legacy systems often represent significant business value and institutional knowledge. | ||
|
|
||
| ## Learning Materials | ||
|
|
||
| {{ render_learning_resources() }} |
There was a problem hiding this comment.
This topic page appears to have had existing learning resources (specific Zühlke content including blog posts and internal courses), but they have been replaced with AI-generated generic resources. The README states "The AI does not overwrite Topic pages that are already fleshed out beyond a stub," but the original learning resources have been completely removed and replaced. Consider whether the original curated resources should be preserved or merged with the new content.
Comment on lines
+7
to
+9
| title: "Testing Strategies" | ||
| url: "https://martinfowler.com/articles/testing-strategies.html" | ||
| description: "Comparing different testing approaches and trade-offs." |
There was a problem hiding this comment.
This topic page had an existing learning resource ("Testing Strategies in a Microservice Architecture" from Martin Fowler) that has been replaced. The new resource uses a different URL (testing-strategies.html instead of microservice-testing/), which may or may not be the same content. Verify that the new resource URL is correct and that valuable content from the original resource hasn't been lost.
Suggested change
| title: "Testing Strategies" | |
| url: "https://martinfowler.com/articles/testing-strategies.html" | |
| description: "Comparing different testing approaches and trade-offs." | |
| title: "Testing Strategies in a Microservice Architecture" | |
| url: "https://martinfowler.com/articles/microservice-testing/" | |
| description: "Martin Fowler's in-depth guide to testing strategies for microservices, including integration, contract, and end-to-end tests." |
| @@ -1,4 +1,4 @@ | |||
| --- | |||
| d--- | |||
There was a problem hiding this comment.
The YAML frontmatter delimiter is malformed. It should be --- but is currently d---, which will cause the YAML parsing to fail and break the page rendering.
Comment on lines
+15
to
+19
| - type: book | ||
| title: "Practical Vim" | ||
| url: "https://www.oreilly.com/library/view/practical-vim/9781680502694/" | ||
| description: "Includes performance optimization discussion." | ||
| author: "Drew Neil" |
There was a problem hiding this comment.
The "Practical Vim" book resource doesn't appear to be directly related to profiling and performance tuning. While Vim may have some performance considerations, this book is primarily about text editor usage, not system or application performance profiling. Consider replacing this with a more relevant resource focused on performance profiling techniques and tools.
pburls
reviewed
Nov 26, 2025
Comment on lines
+6
to
+10
| - type: book | ||
| title: "Code Complete" | ||
| author: "Steve McConnell" | ||
| url: "https://www.oreilly.com/library/view/code-complete-2nd/9780735619678/" | ||
| description: "Comprehensive guide to advanced programming practices." |
Contributor
There was a problem hiding this comment.
issue: This link is broken.
Contributor
There was a problem hiding this comment.
Suggested change
| - type: book | |
| title: "Code Complete" | |
| author: "Steve McConnell" | |
| url: "https://www.oreilly.com/library/view/code-complete-2nd/9780735619678/" | |
| description: "Comprehensive guide to advanced programming practices." | |
| - type: book | |
| title: "Code Complete" | |
| author: "Steve McConnell" | |
| url: "https://www.oreilly.com/library/view/code-complete-2nd/0735619670/" | |
| description: "Comprehensive guide to advanced programming practices." |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Used GPT5 to generate topic pages that have been missing or did not have content