feat(docs): reframe project identity around 'How You Build Matters'#841
Open
FelixTJDietrich wants to merge 10 commits intomainfrom
Open
feat(docs): reframe project identity around 'How You Build Matters'#841FelixTJDietrich wants to merge 10 commits intomainfrom
FelixTJDietrich wants to merge 10 commits intomainfrom
Conversation
Reframe Hephaestus around "How You Build Matters" — formative practice analytics grounded in Cognitive Apprenticeship theory. Rewrite README, landing page, about page, and docs to surface key differentiators: four health dimensions, practice detection, and formative coaching. - Add conceptual model docs with domain model + architecture diagrams - Add HyLiMo research diagrams (class + component) - Replace placeholder copy with specific value propositions - Surface Practice Detection as core feature across all pages - Remove unexplained jargon (SRL-guided → structured reflection) - Update tagline across all 14+ locations Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
github-actions
bot
added
documentation
Contributor
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughDocs and UI rebrand to "How You Build Matters"; add a new conceptual domain model and Guidance/CAMethod in HYL; introduce architecture and domain diagrams; reframe product narrative to an Observe→Detect→Guide→Grow pipeline with practice-detection, AI mentor, and growth tracking; minor sidebar and .gitignore updates. Changes
Sequence Diagram(s)mermaid Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
📝 Coding Plan
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Contributor
📚 Documentation PreviewThis PR includes documentation changes. A preview has been deployed: Preview for commit af8f28f. Updates automatically on new commits. |
Contributor
There was a problem hiding this comment.
Pull request overview
Reframes Hephaestus’ public-facing identity around “How You Build Matters”, aligning the landing/about pages, README, and Docusaurus docs with a cohesive “formative practice analytics” narrative and adding conceptual model documentation.
Changes:
- Updates webapp landing/about copy to emphasize practice detection, multi-dimensional health, and formative coaching.
- Revises Docusaurus homepage + user docs messaging and adds a new Conceptual Model contributor page.
- Rewrites the README to reflect the new framing, feature set, and conceptual/architecture overview (including canonical HyLiMo diagrams).
Reviewed changes
Copilot reviewed 16 out of 16 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| webapp/src/components/info/landing/LandingWhyChooseSection.tsx | Updates “why choose” section copy and icons to reflect “Practices, Not Just Metrics” positioning. |
| webapp/src/components/info/landing/LandingHeroSection.tsx | Replaces hero headline/subtitle with the new “How You Build Matters” messaging. |
| webapp/src/components/info/landing/LandingFeaturesSection.tsx | Expands features from 2 to 3 cards, adding “Practice Detection” and reframing AI mentor copy. |
| webapp/src/components/info/about/AboutMissionSection.tsx | Updates mission/feature grid and adds “Practice Detection” as a core feature. |
| webapp/src/components/info/about/AboutHeroSection.tsx | Updates about hero text to match the new product framing. |
| docs/user/overview.mdx | Rewrites user overview intro and adds a Practice Detection section + workspace management callout. |
| docs/user/ai-mentor.mdx | Updates intro copy (“AI coach”) for consistency with the new framing. |
| docs/src/pages/index.tsx | Updates docs homepage hero + SEO description to the new tagline and narrative. |
| docs/src/components/HomepageFeatures/index.tsx | Updates docs homepage feature list to include “Practice Detection” and new AI mentor copy. |
| docs/sidebars.contributor.ts | Adds the new conceptual model page to the contributor sidebar. |
| docs/docusaurus.config.ts | Updates the site tagline to “How You Build Matters”. |
| docs/contributor/overview.mdx | Updates contributor overview framing to “formative practice analytics” + four dimensions. |
| docs/contributor/conceptual-model.mdx | Adds new conceptual model page with Mermaid diagrams, mappings, and theory grounding. |
| docs/research/domain-model.hyl | Adds canonical HyLiMo domain model diagram source. |
| docs/research/architecture.hyl | Adds canonical HyLiMo architecture diagram source. |
| README.md | Full rewrite to match new identity, pipeline, dimensions, features, and updated roadmap. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (1)
webapp/src/components/info/landing/LandingFeaturesSection.tsx (1)
81-81: Use semantic color token instead of hard-coded blue.Line 81 introduces a hard-coded Tailwind color (
text-blue-500). Prefer a semantic token to keep theme consistency.Suggested change
- <ScanSearch className="h-5 w-5 text-blue-500" /> + <ScanSearch className="h-5 w-5 text-primary" />As per coding guidelines, "Prefer semantic Tailwind tokens (bg-surface, bg-background, text-foreground, text-muted, border-border) over hard-coded color values."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@webapp/src/components/info/landing/LandingFeaturesSection.tsx` at line 81, The ScanSearch icon in LandingFeaturesSection uses a hard-coded Tailwind color class ("text-blue-500"); replace it with a semantic token (e.g., "text-foreground" or "text-muted" per our style guide) by updating the className on the ScanSearch element to use the semantic token instead of "text-blue-500" (ensure the chosen token matches visual intent and is consistent with other icons in LandingFeaturesSection).
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/contributor/conceptual-model.mdx`:
- Line 212: Update the rendered sentence so the link text uses the `HyLiMo`
capitalization for consistency with Line 207: replace the plaintext/link label
`hylimo.github.io` with `HyLiMo` (keeping the URL https://hylimo.github.io
unchanged) in the sentence "Render these at ... by pasting the file contents."
This ensures the visible link text matches the project's preferred
capitalization while preserving the existing link target.
In `@README.md`:
- Around line 20-84: Markdown lint error MD040 is caused by three untyped fenced
code blocks; update each fence to include the text language identifier by
replacing the opening fences for the blocks containing "Observe → Detect →
Coach → Grow", the domain-model diagram starting with "Participant → performs
→ Activity → on → Artifact", and the ASCII architecture box beginning
"Hephaestus Platform" so they read ```text instead of ```, ensuring all three
fenced blocks use the text language identifier to satisfy Markdownlint.
---
Nitpick comments:
In `@webapp/src/components/info/landing/LandingFeaturesSection.tsx`:
- Line 81: The ScanSearch icon in LandingFeaturesSection uses a hard-coded
Tailwind color class ("text-blue-500"); replace it with a semantic token (e.g.,
"text-foreground" or "text-muted" per our style guide) by updating the className
on the ScanSearch element to use the semantic token instead of "text-blue-500"
(ensure the chosen token matches visual intent and is consistent with other
icons in LandingFeaturesSection).
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 0f64ba9c-764c-449e-b96c-a9f0e17ba22c
📒 Files selected for processing (16)
README.mddocs/contributor/conceptual-model.mdxdocs/contributor/overview.mdxdocs/docusaurus.config.tsdocs/research/architecture.hyldocs/research/domain-model.hyldocs/sidebars.contributor.tsdocs/src/components/HomepageFeatures/index.tsxdocs/src/pages/index.tsxdocs/user/ai-mentor.mdxdocs/user/overview.mdxwebapp/src/components/info/about/AboutHeroSection.tsxwebapp/src/components/info/about/AboutMissionSection.tsxwebapp/src/components/info/landing/LandingFeaturesSection.tsxwebapp/src/components/info/landing/LandingHeroSection.tsxwebapp/src/components/info/landing/LandingWhyChooseSection.tsx
| - **Domain Model**: [`docs/research/domain-model.hyl`](https://github.com/ls1intum/Hephaestus/blob/main/docs/research/domain-model.hyl) | ||
| - **Architecture**: [`docs/research/architecture.hyl`](https://github.com/ls1intum/Hephaestus/blob/main/docs/research/architecture.hyl) | ||
|
|
||
| Render these at [hylimo.github.io](https://hylimo.github.io) by pasting the file contents. |
Contributor
There was a problem hiding this comment.
Use consistent platform naming in link text.
Prefer HyLiMo capitalization in the rendered sentence for consistency with Line 207.
Suggested change
-Render these at [hylimo.github.io](https://hylimo.github.io) by pasting the file contents.
+Render these at [HyLiMo](https://hylimo.github.io) by pasting the file contents.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| Render these at [hylimo.github.io](https://hylimo.github.io) by pasting the file contents. | |
| Render these at [HyLiMo](https://hylimo.github.io) by pasting the file contents. |
🧰 Tools
🪛 LanguageTool
[uncategorized] ~212-~212: The official name of this software platform is spelled with a capital “H”.
Context: ...hitecture.hyl) Render these at hylimo.github.io by pastin...
(GITHUB)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/contributor/conceptual-model.mdx` at line 212, Update the rendered
sentence so the link text uses the `HyLiMo` capitalization for consistency with
Line 207: replace the plaintext/link label `hylimo.github.io` with `HyLiMo`
(keeping the URL https://hylimo.github.io unchanged) in the sentence "Render
these at ... by pasting the file contents." This ensures the visible link text
matches the project's preferred capitalization while preserving the existing
link target.
Comment on lines
+20
to
+84
| ``` | ||
| Observe → Detect → Coach → Grow | ||
| ``` | ||
|
|
||
| - **Weekly Leaderboard:** Stay motivated with a dynamic leaderboard that updates in real time via GitHub integration. Earn points for review activity, view detailed stats, and easily copy pull request links. | ||
| 1. **Observe**: Ingest development activity from code platforms (GitHub, GitLab) as an immutable activity event ledger | ||
| 2. **Detect**: Identify behavioral practices — both beneficial and detrimental — across four health dimensions | ||
| 3. **Coach**: Deliver formative feedback through AI mentoring, practice detection, and gamification | ||
| 4. **Grow**: Track participant trajectories to adapt coaching intensity as competence develops | ||
|
|
||
| - **Team Competitions:** Foster a collaborative spirit with team leaderboards spanning multiple repositories and options to filter the associated activities via labels. | ||
| ### Four Health Dimensions | ||
|
|
||
| - **Leagues:** Engage in a structured league system where consistent review efforts build an Elo-like ranking — adding a competitive edge to your code reviews. | ||
| | Dimension | What it measures | Example | | ||
| |-----------|-----------------|---------| | ||
| | **Technical** | Domain skill quality | Review thoroughness, bad practice rate | | ||
| | **Process** | Workflow effectiveness | Lead time, WIP count, PR abandonment | | ||
| | **Social** | Collaboration quality | Review reciprocity, cross-team engagement | | ||
| | **Cognitive** | Learning & self-regulation | Declining bad practice rate, reflection depth | | ||
|
|
||
| - **Automated Recognition:** Celebrate excellence with weekly Slack notifications that honor the top three reviewers and link directly to the previous week's leaderboard. | ||
| ## Features | ||
|
|
||
| 2. **Heph (Conversational AI Mentor)** | ||
| ### Practice Detection | ||
|
|
||
| - **SRL-guided reflection:** Run structured, AI-assisted sessions that support self-regulated learning (goals → strategies → reflection) tailored to agile project work. | ||
| - **Automated standups:** Turn weekly insights into a concise standup table to streamline team communication and accountability. | ||
| - **Repo context awareness:** Ground guidance in actual activity (issues, commits, reviews, PRs) to deliver objective, data-informed feedback and next steps. | ||
| AI-powered analysis of pull requests that identifies anti-patterns (missing descriptions, oversized changes, incomplete templates) with lifecycle-aware severity — draft PRs receive gentler feedback, ready-to-merge PRs receive stricter review. Contributors can mark findings as fixed, won't fix, or incorrect, closing the feedback loop. | ||
|
|
||
| ### AI Mentor (Heph) | ||
|
|
||
| A conversational AI mentor grounded in your actual project activity. Heph supports self-regulated learning through structured reflection sessions (goals → strategies → reflection), generates weekly standup summaries, and surfaces relevant pull requests and action items — all driven by real data, not guesswork. | ||
|
|
||
| ### Gamification | ||
|
|
||
| Transparent, multi-dimensional engagement through weekly leaderboards, an Elo-like league system for persistent ranking, and 60+ achievements across five categories with progression chains from common to mythic rarity. Automated Slack digests recognize top contributors each week. | ||
|
|
||
| ### Agent Orchestration | ||
|
|
||
| Run AI coding agents (Claude Code, Codex, OpenCode) in sandboxed containers with configurable LLM providers, resource limits, and concurrency caps. Agents participate in the same activity stream as human contributors. | ||
|
|
||
| ## Domain Model | ||
|
|
||
| Seven domain-independent concepts form the analytical pipeline: | ||
|
|
||
| ``` | ||
| Participant → performs → Activity → on → Artifact | ||
| ↓ | ||
| aggregates into → Signal → bears on → Practice | ||
| ↓ | ||
| tracked over time → Trajectory | ||
|
|
||
| All scoped to: Project | ||
| ``` | ||
|
|
||
| | Concept | Description | Software instance | | ||
| |---------|-------------|-------------------| | ||
| | **Project** | Bounded endeavor with goals and norms | Workspace / Repository | | ||
| | **Participant** | Person or agent developing practice | Developer, Bot | | ||
| | **Artifact** | Tangible work product | PR, Review, Issue, Comment | | ||
| | **Activity** | Immutable record of what happened | ActivityEvent | | ||
| | **Practice** | Named behavioral pattern | "Gives substantive reviews" | | ||
| | **Signal** | Quantified health measure along a dimension | Review thoroughness: 0.85 | | ||
| | **Trajectory** | Developmental arc over time | Improving social health | | ||
|
|
||
| See the full [Conceptual Model](https://ls1intum.github.io/Hephaestus/contributor/conceptual-model) for cross-domain instantiation, architecture diagrams, and the Cognitive Apprenticeship mapping. | ||
|
|
||
| ## Architecture | ||
|
|
||
| ``` |
Contributor
There was a problem hiding this comment.
Add language identifiers to fenced code blocks.
Markdownlint MD040 is triggered at Lines 20, 60, and 84 due to untyped fences.
Suggested change
-```
+```text
Observe → Detect → Coach → Grow@@
- +text
Participant → performs → Activity → on → Artifact
↓
aggregates into → Signal → bears on → Practice
↓
tracked over time → Trajectory
All scoped to: Project
@@
-```
+```text
┌──────────────────────────────────────────────────────┐
│ Hephaestus Platform │
│ │
│ Web App Application Server Webhook Ingest│
│ (React 19) ───▶ (Spring Boot 3.5) ◀── (Hono) │
│ │ │ ▲ │
│ ▼ ▼ │ │
│ Intelligence Service (Hono · LangGraph) │ │
└───────────────────────┬───────────────────────┘ │
│ │
┌───────────────────┼──────────────────┐ │
▼ ▼ ▼ │
Data Infra Platform Services Code Platforms──┘
PostgreSQL Keycloak · Slack GitHub · GitLab
NATS LLM · Langfuse
</details>
<details>
<summary>🧰 Tools</summary>
<details>
<summary>🪛 markdownlint-cli2 (0.21.0)</summary>
[warning] 20-20: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
---
[warning] 60-60: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
---
[warning] 84-84: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
</details>
</details>
<details>
<summary>🤖 Prompt for AI Agents</summary>
Verify each finding against the current code and only fix it if needed.
In @README.md around lines 20 - 84, Markdown lint error MD040 is caused by three
untyped fenced code blocks; update each fence to include the text language
identifier by replacing the opening fences for the blocks containing "Observe →
Detect → Coach → Grow", the domain-model diagram starting with "Participant
→ performs → Activity → on → Artifact", and the ASCII architecture box beginning
"Hephaestus Platform" so they read text instead of , ensuring all three
fenced blocks use the text language identifier to satisfy Markdownlint.
</details>
<!-- fingerprinting:phantom:poseidon:hawk -->
<!-- This is an auto-generated comment by CodeRabbit -->
Add 8th domain concept (Guidance) to close the coaching loop: Signal → Guidance → Participant. Add CAMethod enum (6 CA methods). Remove access modifiers, add user-facing use cases as methods to all 8 classes. Fix architecture.hyl to use correct dependsOn syntax. Update Mermaid diagrams and README to match. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
♻️ Duplicate comments (2)
docs/contributor/conceptual-model.mdx (1)
261-261:⚠️ Potential issue | 🟡 MinorUse
HyLiMocapitalization in the rendered link text.Line 261 uses lowercase link text, which is inconsistent with the project name used above.
Suggested fix
-Render these at [hylimo.github.io](https://hylimo.github.io) by pasting the file contents. +Render these at [HyLiMo](https://hylimo.github.io) by pasting the file contents.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/contributor/conceptual-model.mdx` at line 261, The rendered link text currently uses lowercase "hylimo.github.io"; update the link label to use the project capitalization "HyLiMo" (i.e., render as [HyLiMo](https://hylimo.github.io)) so the displayed text matches the project name; locate the occurrence of the URL hyperlink in conceptual-model.mdx and replace the link text only, leaving the URL unchanged.README.md (1)
20-22:⚠️ Potential issue | 🟡 MinorAdd language identifiers to fenced code blocks (MD040 still failing).
Line 20, Line 60, and Line 87 use untyped fences, which keeps markdownlint warning
MD040active.Suggested fix
-``` +```text Observe → Detect → Coach → Grow-
+text
Participant → performs → Activity → on → Artifact
↓
aggregates into → Signal ← detects ← Practice
↓ ↓
triggers → Guidance → targets → Participant
↓
feeds → Trajectory ← tracked over ← PracticeAll scoped to: Project
-``` +```text ┌──────────────────────────────────────────────────────┐ │ Hephaestus Platform │ │ │ │ Web App Application Server Webhook Ingest│ │ (React 19) ───▶ (Spring Boot 3.5) ◀── (Hono) │ │ │ │ ▲ │ │ ▼ ▼ │ │ │ Intelligence Service (Hono · LangGraph) │ │ └───────────────────────┬───────────────────────┘ │ │ │ ┌───────────────────┼──────────────────┐ │ ▼ ▼ ▼ │ Data Infra Platform Services Code Platforms──┘ PostgreSQL Keycloak · Slack GitHub · GitLab NATS LLM · Langfuse</details> Also applies to: 60-70, 87-103 <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@README.mdaround lines 20 - 22, Three fenced code blocks containing the flow
"Observe → Detect → Coach → Grow", the Participant/Signal diagram starting
with "Participant → performs → Activity", and the ASCII diagram beginning
"┌──────────────────────────────────────────────────────┐" are using untitled```text) so the blocks become ```text ... ``` to satisfy markdownlint MD040; locate these blocks by their exact content strings and replace the leading ``` with ```text for each occurrence.
🧹 Nitpick comments (1)
docs/research/architecture.hyl (1)
1-1: Update the component-count label for consistency.Line 1 says “7 Components”, but this file declares 10 components. Consider renaming the heading (or grouping externals) to avoid reader confusion.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/research/architecture.hyl` at line 1, The heading "Hephaestus Architecture — 7 Components" is inconsistent with the file's declared 10 components; update the heading text to reflect the correct count (e.g., "Hephaestus Architecture — 10 Components") or alternatively revise the document to group or label externals so the displayed count matches the components listed; locate and change the heading string "Hephaestus Architecture — 7 Components" accordingly.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/contributor/conceptual-model.mdx`:
- Around line 232-243: The document claims "all six methods" of Cognitive
Apprenticeship but the table includes a seventh row "Fading"; update the opening
sentence to "all seven methods" (or alternatively remove the Fading row if you
intended six) so the claim matches the table, and ensure any other mentions of
"six" in the "Cognitive Apprenticeship" section are adjusted to "seven" to keep
the content consistent.
In `@docs/research/architecture.hyl`:
- Around line 71-72: The diagram currently has
WebhookIngest.provides("Webhooks", ...) which inverts the flow; change the model
so CodePlatforms is the provider and WebhookIngest is the consumer — e.g.,
replace the WebhookIngest.provides(...) usage by making
CodePlatforms.provides("Webhooks", ...) (or add an explicit dependency edge
CodePlatforms -> WebhookIngest via WebhookIngest.dependsOn(CodePlatforms) /
CodePlatforms.provides(...)) so the arrow points from CodePlatforms to
WebhookIngest; apply the same change for the other occurrence mentioned (lines
100-101).
---
Duplicate comments:
In `@docs/contributor/conceptual-model.mdx`:
- Line 261: The rendered link text currently uses lowercase "hylimo.github.io";
update the link label to use the project capitalization "HyLiMo" (i.e., render
as [HyLiMo](https://hylimo.github.io)) so the displayed text matches the project
name; locate the occurrence of the URL hyperlink in conceptual-model.mdx and
replace the link text only, leaving the URL unchanged.
In `@README.md`:
- Around line 20-22: Three fenced code blocks containing the flow "Observe →
Detect → Coach → Grow", the Participant/Signal diagram starting with
"Participant → performs → Activity", and the ASCII diagram beginning
"┌──────────────────────────────────────────────────────┐" are using untitled
``` fences; update each opening fence to include a language identifier (use
```text) so the blocks become ```text ... ``` to satisfy markdownlint MD040;
locate these blocks by their exact content strings and replace the leading ```
with ```text for each occurrence.
---
Nitpick comments:
In `@docs/research/architecture.hyl`:
- Line 1: The heading "Hephaestus Architecture — 7 Components" is inconsistent
with the file's declared 10 components; update the heading text to reflect the
correct count (e.g., "Hephaestus Architecture — 10 Components") or alternatively
revise the document to group or label externals so the displayed count matches
the components listed; locate and change the heading string "Hephaestus
Architecture — 7 Components" accordingly.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 692dd3b1-c1bd-4e80-ab3a-bfa4fe459b05
📒 Files selected for processing (5)
.gitignoreREADME.mddocs/contributor/conceptual-model.mdxdocs/research/architecture.hyldocs/research/domain-model.hyl
🚧 Files skipped from review as they are similar to previous changes (1)
- docs/research/domain-model.hyl
Comment on lines
+71
to
+72
| webhookIn = WebhookIngest.provides("Webhooks", 0.75, dist = 50) | ||
|
|
Contributor
There was a problem hiding this comment.
Fix webhook dependency direction in the diagram model.
The canonical diagram currently models CodePlatforms as depending on WebhookIngest. That inverts the intended flow (code platforms emit webhooks; ingest consumes them).
Suggested fix
- // WebhookIngest provides Webhooks
- webhookIn = WebhookIngest.provides("Webhooks", 0.75, dist = 50)
+ // WebhookIngest consumes webhooks from CodePlatforms
+ webhookIn = WebhookIngest.requires("Webhooks", 0.75)
@@
- // CodePlatforms → WebhookIngest
- cpWebhooks = CodePlatforms.requires("push", 0.5)
- cpWebhooks dependsOn webhookIn
+ // CodePlatforms → WebhookIngest
+ cpWebhooks = CodePlatforms.provides("Webhooks", 0.5, dist = 50)
+ webhookIn dependsOn cpWebhooksAlso applies to: 100-101
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/research/architecture.hyl` around lines 71 - 72, The diagram currently
has WebhookIngest.provides("Webhooks", ...) which inverts the flow; change the
model so CodePlatforms is the provider and WebhookIngest is the consumer — e.g.,
replace the WebhookIngest.provides(...) usage by making
CodePlatforms.provides("Webhooks", ...) (or add an explicit dependency edge
CodePlatforms -> WebhookIngest via WebhookIngest.dependsOn(CodePlatforms) /
CodePlatforms.provides(...)) so the arrow points from CodePlatforms to
WebhookIngest; apply the same change for the other occurrence mentioned (lines
100-101).
Add explicit scope statement to README, generalize framework-level terminology (engineering→project metrics, standup→progress summaries), fix domain-independent concept definitions leaking SE terms, and expand SEO keywords for researcher and practitioner discoverability. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
♻️ Duplicate comments (3)
README.md (1)
20-20:⚠️ Potential issue | 🟡 MinorAdd language identifiers to fenced code blocks (MD040).
Opening fences at Line 20, Line 60, and Line 87 should specify a language (use
textfor ASCII/flow content), otherwise markdownlint will keep warning.Suggested fix
-``` +```text Observe → Detect → Coach → Grow-
+text
Participant → performs → Activity → on → Artifact
↓
aggregates into → Signal ← detects ← Practice
↓ ↓
triggers → Guidance → targets → Participant
↓
feeds → Trajectory ← tracked over ← PracticeAll scoped to: Project
-``` +```text ┌──────────────────────────────────────────────────────┐ │ Hephaestus Platform │ │ │ │ Web App Application Server Webhook Ingest│ │ (React 19) ───▶ (Spring Boot 3.5) ◀── (Hono) │ │ │ │ ▲ │ │ ▼ ▼ │ │ │ Intelligence Service (Hono · LangGraph) │ │ └───────────────────────┬───────────────────────┘ │ │ │ ┌───────────────────┼──────────────────┐ │ ▼ ▼ ▼ │ Data Infra Platform Services Code Platforms──┘ PostgreSQL Keycloak · Slack GitHub · GitLab NATS LLM · Langfuse</details> Also applies to: 60-60, 87-87 <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@README.mdat line 20, Three fenced code blocks in README.md (the ASCII
diagrams starting with "Observe → Detect → Coach → Grow", the flow
beginning "Participant → performs → Activity → on → Artifact", and the
"Hephaestus Platform" diagram) are missing language identifiers; update each
opening fence fromtotext to satisfy MD040 (usetextfor ASCII/flow
content) so markdownlint stops warning.</details> </blockquote></details> <details> <summary>docs/contributor/conceptual-model.mdx (2)</summary><blockquote> `232-243`: _⚠️ Potential issue_ | _🟡 Minor_ **Inconsistency between "six methods" claim and table content.** Line 232 states "all six methods" but the table includes **Fading** as a seventh row. Since Fading is marked as "Planned" and isn't in the `CAMethod` enum (lines 111-119), consider clarifying this in the prose—e.g., "the six core methods... with Fading as a planned extension." <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In `@docs/contributor/conceptual-model.mdx` around lines 232 - 243, The text claims "all six methods" but the table includes a seventh row "Fading" which isn't in the CAMethod enum; either remove/omit Fading from the table or update the prose to say "the six core methods... with Fading as a planned extension", or if Fading should be supported now, add it to the CAMethod enum and change its status to Current—update the prose and table consistently and ensure CAMethod enum and the table rows match (referencing the CAMethod enum and the "Fading" table row). ``` </details> --- `261-261`: _⚠️ Potential issue_ | _🟡 Minor_ **Use consistent platform naming in link text.** For consistency with Line 256, use "HyLiMo" capitalization in the link text. ```diff -Render these at [hylimo.github.io](https://hylimo.github.io) by pasting the file contents. +Render these at [HyLiMo](https://hylimo.github.io) by pasting the file contents. ``` <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In `@docs/contributor/conceptual-model.mdx` at line 261, Update the link text in the sentence that currently reads "Render these at [hylimo.github.io](https://hylimo.github.io) by pasting the file contents." to use the consistent "HyLiMo" capitalization (i.e., "Render these at [HyLiMo](https://hylimo.github.io) ..."); locate the occurrence in docs/contributor/conceptual-model.mdx and replace the link label only, leaving the URL unchanged. ``` </details> </blockquote></details> </blockquote></details> <details> <summary>🤖 Prompt for all review comments with AI agents</summary>Verify each finding against the current code and only fix it if needed.
Duplicate comments:
In@docs/contributor/conceptual-model.mdx:
- Around line 232-243: The text claims "all six methods" but the table includes
a seventh row "Fading" which isn't in the CAMethod enum; either remove/omit
Fading from the table or update the prose to say "the six core methods... with
Fading as a planned extension", or if Fading should be supported now, add it to
the CAMethod enum and change its status to Current—update the prose and table
consistently and ensure CAMethod enum and the table rows match (referencing the
CAMethod enum and the "Fading" table row).- Line 261: Update the link text in the sentence that currently reads "Render
these at hylimo.github.io by pasting the file
contents." to use the consistent "HyLiMo" capitalization (i.e., "Render these at
HyLiMo ..."); locate the occurrence in
docs/contributor/conceptual-model.mdx and replace the link label only, leaving
the URL unchanged.In
@README.md:
- Line 20: Three fenced code blocks in README.md (the ASCII diagrams starting
with "Observe → Detect → Coach → Grow", the flow beginning "Participant →
performs → Activity → on → Artifact", and the "Hephaestus Platform" diagram) are
missing language identifiers; update each opening fence fromtotext to
satisfy MD040 (usetextfor ASCII/flow content) so markdownlint stops warning.</details> --- <details> <summary>ℹ️ Review info</summary> <details> <summary>⚙️ Run configuration</summary> **Configuration used**: defaults **Review profile**: CHILL **Plan**: Pro **Run ID**: `068b746a-d4dd-4af5-86cc-ce2b4ef226d5` </details> <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between 1c0f4fe1526536fb8546da6b96a7dd5a13dd3e29 and 9b5501a77747acdcf565a632224367b7e60aab80. </details> <details> <summary>📒 Files selected for processing (3)</summary> * `README.md` * `docs/contributor/conceptual-model.mdx` * `docs/docusaurus.config.ts` </details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
- Pipeline: Coach→Guide in README (was contradicting own domain model) - Mermaid: add missing Valence enum, Practice→Valence edge, AS→IS link - CA mapping: clarify Fading as meta-principle (was "six methods" with 7 rows) - Data flows: rename Coach→Guide, reorder to match pipeline - Meta: update stale docusaurus descriptions + keywords to new framing - Terminology: AI coach→AI mentor in ai-mentor.mdx - README: remove SRL jargon, fix scope statement placement, rename Gamification→Code Review Gamification for cross-file consistency Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
♻️ Duplicate comments (2)
README.md (1)
22-24:⚠️ Potential issue | 🟡 MinorAdd language identifiers to fenced code blocks (MD040).
The three fenced blocks starting at Lines 22, 62, and 89 should declare a language (e.g.,
text) to satisfy markdownlint consistently.Suggested fix
-``` +```text Observe → Detect → Guide → Grow@@
-+text
Participant → performs → Activity → on → Artifact
↓
aggregates into → Signal ← detects ← Practice
↓ ↓
triggers → Guidance → targets → Participant
↓
feeds → Trajectory ← tracked over ← PracticeAll scoped to: Project
@@ -``` +```text ┌──────────────────────────────────────────────────────┐ │ Hephaestus Platform │ │ │ │ Web App Application Server Webhook Ingest│ │ (React 19) ───▶ (Spring Boot 3.5) ◀── (Hono) │ │ │ │ ▲ │ │ ▼ ▼ │ │ │ Intelligence Service (Hono · LangGraph) │ │ └───────────────────────┬───────────────────────┘ │ │ │ ┌───────────────────┼──────────────────┐ │ ▼ ▼ ▼ │ Data Infra Platform Services Code Platforms──┘ PostgreSQL Keycloak · Slack GitHub · GitLab NATS LLM · Langfuse</details> Also applies to: 62-72, 89-105 <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@README.mdaround lines 22 - 24, Add explicit language identifiers (e.g.,
"text") to the three fenced code blocks that currently lack them: the block
containing "Observe → Detect → Guide → Grow", the larger diagram block
beginning with "Participant → performs → Activity → on → Artifact" (the
flow/Signal/Guidance diagram), and the ASCII diagram starting with
"┌──────────────────────────────────────────────────────┐" (Hephaestus Platform
diagram). Edit the README.md fenced code fences that wrap those exact blocks
(replacewithtext) so markdownlint MD040 is satisfied while preserving
the inner content and spacing.</details> </blockquote></details> <details> <summary>docs/contributor/conceptual-model.mdx (1)</summary><blockquote> `270-270`: _⚠️ Potential issue_ | _🟡 Minor_ **Use consistent `HyLiMo` naming in rendered link text.** Line 270 currently shows lowercase link text, which is inconsistent with Line 265 and project naming. <details> <summary>Suggested fix</summary> ```diff -Render these at [hylimo.github.io](https://hylimo.github.io) by pasting the file contents. +Render these at [HyLiMo](https://hylimo.github.io) by pasting the file contents. ``` </details> <details> <summary>🤖 Prompt for AI Agents</summary> ``` Verify each finding against the current code and only fix it if needed. In `@docs/contributor/conceptual-model.mdx` at line 270, The link text on Line 270 currently uses lowercase rendering for the URL; update the rendered link label that points to https://hylimo.github.io so the visible text is "HyLiMo" (capital H,L,M) to match the project naming and the link at Line 265, preserving the existing URL and Markdown/MDX link syntax. ``` </details> </blockquote></details> </blockquote></details> <details> <summary>🤖 Prompt for all review comments with AI agents</summary>Verify each finding against the current code and only fix it if needed.
Duplicate comments:
In@docs/contributor/conceptual-model.mdx:
- Line 270: The link text on Line 270 currently uses lowercase rendering for the
URL; update the rendered link label that points to https://hylimo.github.io so
the visible text is "HyLiMo" (capital H,L,M) to match the project naming and the
link at Line 265, preserving the existing URL and Markdown/MDX link syntax.In
@README.md:
- Around line 22-24: Add explicit language identifiers (e.g., "text") to the
three fenced code blocks that currently lack them: the block containing "Observe
→ Detect → Guide → Grow", the larger diagram block beginning with
"Participant → performs → Activity → on → Artifact" (the flow/Signal/Guidance
diagram), and the ASCII diagram starting with
"┌──────────────────────────────────────────────────────┐" (Hephaestus Platform
diagram). Edit the README.md fenced code fences that wrap those exact blocks
(replacewithtext) so markdownlint MD040 is satisfied while preserving
the inner content and spacing.</details> --- <details> <summary>ℹ️ Review info</summary> <details> <summary>⚙️ Run configuration</summary> **Configuration used**: defaults **Review profile**: CHILL **Plan**: Pro **Run ID**: `56671ea7-65af-42c7-b10f-805bfa991513` </details> <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between 9b5501a77747acdcf565a632224367b7e60aab80 and 242a5d8ee149980f6512e82c90ea223660434b77. </details> <details> <summary>📒 Files selected for processing (4)</summary> * `README.md` * `docs/contributor/conceptual-model.mdx` * `docs/docusaurus.config.ts` * `docs/user/ai-mentor.mdx` </details> <details> <summary>🚧 Files skipped from review as they are similar to previous changes (1)</summary> * docs/docusaurus.config.ts </details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
- Practice Detection: replace aspirational "beneficial practices" and "four dimension scoring" claims with accurate "anti-pattern detection" and "feedback loop" descriptions matching shipped functionality - Pipeline prose: Coach→Guide across all hero/subtitle copy for consistency with domain model pipeline (Observe→Detect→Guide→Grow) - overview.mdx: update stale frontmatter description Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Rewrite all public-facing copy to lead with the Observe→Detect→Guide→Grow
pipeline instead of "AI mentoring and gamification":
- Feature cards: Code Review Gamification / AI Mentor / Practice Detection
→ Practice Detection (Detect) / Multi-Channel Guidance (Guide) /
Growth Tracking (Grow)
- Hero subtitle: kill "through AI mentoring and gamification", surface
agent orchestration with "human and AI"
- Why Choose: "summative dashboards for managers" vs "formative feedback
to the people doing the work"
- README: rename Gamification → Recognition & Growth, update Guide step
- Meta descriptions: pipeline-first framing across all surfaces
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (2)
webapp/src/components/info/landing/LandingWhyChooseSection.tsx (1)
7-11: Export the props interface.Per coding guidelines, component prop interfaces should be exported so other modules can reuse them.
Proposed fix
-interface LandingWhyChooseSectionProps { +export interface LandingWhyChooseSectionProps { onSignIn: () => void; onGoToDashboard?: () => void; isSignedIn: boolean; }As per coding guidelines: "Export prop interfaces from components" for files matching
webapp/src/components/**/*.{ts,tsx}.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@webapp/src/components/info/landing/LandingWhyChooseSection.tsx` around lines 7 - 11, The props interface LandingWhyChooseSectionProps should be exported so other modules can reuse it; update the declaration for LandingWhyChooseSectionProps to be exported (e.g., export interface LandingWhyChooseSectionProps { ... }) in the LandingWhyChooseSection component file and ensure any local usages (like the LandingWhyChooseSection component signature) continue to reference the exported interface.webapp/src/components/info/landing/LandingFeaturesSection.tsx (1)
25-27: Use semantic color tokens for the new feature icons.Line 26 and Line 96 hard-code
text-blue-500/text-green-500, which makes these cards drift from the theme palette and dark-mode tuning. Replacing them with existing semantic tokens keeps the new section aligned with the rest of the design system.As per coding guidelines, "Prefer semantic Tailwind tokens (bg-surface, bg-background, text-foreground, text-muted, border-border) over hard-coded color values".🎨 Example adjustment
- <ScanSearch className="h-5 w-5 text-blue-500" /> + <ScanSearch className="h-5 w-5 text-primary" /> … - <TrendingUp className="h-5 w-5 text-green-500" /> + <TrendingUp className="h-5 w-5 text-provider-success-foreground" />Also applies to: 95-97
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@webapp/src/components/info/landing/LandingFeaturesSection.tsx` around lines 25 - 27, Replace hard-coded color classes (e.g., "text-blue-500" and "text-green-500") in LandingFeaturesSection.tsx with semantic Tailwind tokens so the icons follow the theme and dark-mode tuning; specifically update the ScanSearch icon's className and any other icon classNames in the same component (the instances around the earlier and later icon blocks) to use tokens like "text-foreground" for primary/important icons or "text-muted" for secondary/subtle icons (or another appropriate semantic token from our palette such as "text-foreground" / "text-muted" / "border-border") instead of concrete blue/green classes. Ensure you only change the className strings on the icon components (e.g., ScanSearch and the other feature icon elements) to the chosen semantic tokens.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@README.md`:
- Around line 42-45: Several docs and UI files use inconsistent finding-state
labels; standardize them to a single taxonomy. Update README.md,
docs/user/overview.mdx, the HomepageFeatures component
(docs/src/components/HomepageFeatures/index.tsx) and LandingFeaturesSection
(webapp/src/components/info/landing/LandingFeaturesSection.tsx) so they all use
the same labels — e.g., replace any occurrences of "fixed / won't fix /
incorrect" or "fixed / adjusted / not applicable" with the chosen set "fixed /
adjusted / incorrect" (or update all to your preferred single taxonomy), and
ensure any UI strings/props/constants in HomepageFeatures and
LandingFeaturesSection are changed to match that exact phrasing so public docs
and UI labels are consistent.
---
Nitpick comments:
In `@webapp/src/components/info/landing/LandingFeaturesSection.tsx`:
- Around line 25-27: Replace hard-coded color classes (e.g., "text-blue-500" and
"text-green-500") in LandingFeaturesSection.tsx with semantic Tailwind tokens so
the icons follow the theme and dark-mode tuning; specifically update the
ScanSearch icon's className and any other icon classNames in the same component
(the instances around the earlier and later icon blocks) to use tokens like
"text-foreground" for primary/important icons or "text-muted" for
secondary/subtle icons (or another appropriate semantic token from our palette
such as "text-foreground" / "text-muted" / "border-border") instead of concrete
blue/green classes. Ensure you only change the className strings on the icon
components (e.g., ScanSearch and the other feature icon elements) to the chosen
semantic tokens.
In `@webapp/src/components/info/landing/LandingWhyChooseSection.tsx`:
- Around line 7-11: The props interface LandingWhyChooseSectionProps should be
exported so other modules can reuse it; update the declaration for
LandingWhyChooseSectionProps to be exported (e.g., export interface
LandingWhyChooseSectionProps { ... }) in the LandingWhyChooseSection component
file and ensure any local usages (like the LandingWhyChooseSection component
signature) continue to reference the exported interface.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: f902c76a-d5f8-44fb-994a-e8d84ce9e47e
📒 Files selected for processing (10)
README.mddocs/docusaurus.config.tsdocs/src/components/HomepageFeatures/index.tsxdocs/src/pages/index.tsxdocs/user/overview.mdxwebapp/src/components/info/about/AboutHeroSection.tsxwebapp/src/components/info/about/AboutMissionSection.tsxwebapp/src/components/info/landing/LandingFeaturesSection.tsxwebapp/src/components/info/landing/LandingHeroSection.tsxwebapp/src/components/info/landing/LandingWhyChooseSection.tsx
🚧 Files skipped from review as they are similar to previous changes (3)
- docs/docusaurus.config.ts
- docs/src/pages/index.tsx
- webapp/src/components/info/about/AboutMissionSection.tsx
…ation Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…anding - Drop "human and AI" from all hero/tagline copy — Hephaestus coaches people - Agents get context delivery, not coaching - Cognitive dimension: "Understanding and growth" (cognitive debt framing) - Replace "Humans and AI coding agents get same coaching" with grounded-in-data Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…criptions - Replace "right channel at the right time" (5 occurrences) with actual channel list - Replace "guide every contributor toward growth" (9 occurrences) with specifics - Replace "real data, not guesswork" with nothing (every tool claims this) - Replace "celebrate growth" / "first steps to mastery" with factual descriptions - About page: generic pitch → TUM research project origin - Mission blockquote: inspirational fluff → actual differentiating opinion - Meta descriptions: academic jargon → SEO-friendly concrete terms - Overview.mdx: sales pitch → what the tools actually do - Pipeline steps: marketing verbs → technical descriptions Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…inate GitHub specifics Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
github-actions
bot
added
size:XXL
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 join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Description
Reframe Hephaestus around "How You Build Matters" — formative practice analytics grounded in Cognitive Apprenticeship theory. This PR rewrites all public-facing copy (README, landing page, about page, docs) to present a cohesive identity with clear differentiators.
Key changes
What's different about the framing
How to Test
npm run checkpasses (format + lint + typecheck)npm run test:webapppasses (68/68 tests)Summary by CodeRabbit