docs: reframe project around practice-aware guidance - #841
Closed
FelixTJDietrich wants to merge 23 commits into
Closed
docs: reframe project around practice-aware guidance#841FelixTJDietrich wants to merge 23 commits into
FelixTJDietrich wants to merge 23 commits into
Conversation
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)
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 2ca257b. 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
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
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 -->
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 -->
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
github-actions
Bot
added
size:XXL
Rewrite all public-facing copy to lead with "practice-aware guidance" — the core value prop — instead of "AI mentoring and gamification." - Hero/taglines: "Define what good looks like — Hephaestus does the rest" - Feature cards reordered: Practice Detection → Adaptive Coaching → Engagement - Kill "Code Review Gamification" as feature name; replace with pipeline stages - WhyChoose: "formative feedback to contributors" vs "summative dashboards" - Meta descriptions + keywords updated across docusaurus config - Storybook stories updated to match new card framing - README rewritten from scratch with practice-aware guidance structure Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
FelixTJDietrich
force-pushed
the
hephaestus-reframing-architecture
branch
from
March 26, 2026 22:57
af8f28f to
03158cd
Compare
github-actions
Bot
added
the
application-server
- Heading: "How You Build Matters" → "Practice-Aware Guidance for Software Projects" - Delete Greek god etymology and "domain model designed for cross-domain extension" - Move domain model table out of README (already in conceptual-model.mdx) - Simplify roadmap items: kill "developmental arcs", "adaptive fading", "artifact sources" - Deduplicate About page: hero + mission no longer repeat the same sentence 3x - Fix "collaborative projects" → "software projects" everywhere - Kill "repo-grounded AI coaching" and "contribute confidently" in contributor overview - Clean up conceptual model: "problem world", "Goodhart's Law", section titles - Simplify docs index guide-picker paragraph Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
These changes came in from main during the rebase but were not committed with the previous copy changes. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
FelixTJDietrich
changed the title
…SVG rendering - Move .hyl files from docs/research/ to docs/diagrams/ - Replace old 8-concept model (with Signal, Trajectory, Participant, Activity) with new 7-entity model (Project, Contributor, Artifact, Event, Practice, Finding, Guidance) - Add render.sh script using HyLiMo CLI to generate SVGs from .hyl sources - Rework architecture.hyl with relative positioning (rpos) - Embed domain model SVG in README - Replace mermaid diagrams in conceptual-model.mdx with rendered HyLiMo SVGs - Update conceptual-model.mdx content to match new entities - Add docs:render-diagrams npm script Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
github-actions
Bot
added
the
dependencies
The render script incorrectly depended on .context/hylimo/ which only exists on one machine. Now uses @hylimo/cli from devDependencies. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…nd accurate connections - Use connected notation for internal interfaces (within Hephaestus boundary) - Use dependsOn for cross-canvas external interfaces (HyLiMo limitation) - Drop Langfuse and Slack as non-architectural (observability + notifications) - Merge CodePlatforms webhooks + API into single Git interface - Add missing AppServer→CodePlatforms and IntelligenceService→PostgreSQL connections - All external systems use relative positioning from CodePlatforms anchor Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…ech labels - Flat layout (no nesting) so all interfaces use connected notation - Fix WebApp: goes through ApplicationServer to IntelligenceService, not direct - Add missing WebApp→Keycloak auth connection (keycloak-js) - Add missing ApplicationServer→IntelligenceService mentor proxy - Drop technology keywords, use managed/external stereotypes instead - Rename Practice.dimension to Practice.category in domain model Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Architecture: - Replace flat diagram with user's reworked layout (all components inside Hephaestus boundary, connected notation throughout) - Add architecture SVG to README alongside domain model Stale terminology fixes: - README roadmap: Health Signals → Project Health, Trajectories → Guidance Fading - FAQ: GitHub-only → GitHub and GitLab / code platform (4 fixes) - FAQ: remove "guided configuration" claim (does not exist) - conceptual-model.mdx: CaMethod enum → cognitive apprenticeship method - conceptual-model.mdx: data flows updated to match new architecture names - conceptual-model.mdx: Activity summaries → Contributor summaries - system-design.mdx: add HyLiMo as canonical diagram tool alongside StarUML - system-design.mdx: "GitLab planned" → "GitHub and GitLab" (already shipped) - docs/README.md: mention HyLiMo diagrams - docs index.tsx: remove subtitle repeating heading verbatim Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
… across PR - conceptual-model.mdx: severity/reasoning marked Implemented (not missing), Sprint→Milestone, CaMethod→cognitive apprenticeship method - system-design.mdx: gamification→engagement, developer→contributor, sprint→week, StarUML labeled legacy, Agent Sandbox added - README.md: added "evidence" to findings list, fixed alt text - FAQ: GitHub-only→GitHub+GitLab, removed "guided configuration" claim, made answers concrete - 5 files: mentoring→guidance/intelligence service throughout - AboutHeroSection: CA theory→established learning theory - docs/README: added render-diagrams script - package.json: bash prefix for render script portability Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
getting-started.mdx: remove fabricated Dashboard, Artifacts library, in-app notifications, Retrospective templates, pinnable checklists; describe only what exists (Leaderboard, Mentor threads, Settings) conceptual-model.mdx: fix Agent Sandbox LLM path (goes through App Server proxy, not direct), Gamification→Engagement design, dimensions framed as proposed framework README.md: move Inline Guidance from roadmap to Features (shipped), qualify Guidance Fading as partially implemented, dimensions as proposed framework, add inline guidance mention to Practice Detection overview.mdx: real-time→synced, quality→activity, connect repos→auto-sync AboutHeroSection: name Cognitive Apprenticeship explicitly (PhD project) LandingFeaturesSection+HomepageFeatures: quality→activity, sustained good practices→consistent contribution activity FAQ: honest about setup complexity Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Remove Four Health Dimensions from README and conceptual-model (not implemented in code, will revisit later) - Remove Cognitive Apprenticeship mapping and secondary theories from conceptual-model (owner will handle separately) - Remove CA reference from AboutHeroSection — keep copy clean - Simplify data flow #2 back to straightforward arrow notation - Fix FAQ: end users install the GitHub App, not Docker Compose - Update conceptual-model description and codebase mapping (drop CA ref) - Update README link text to match new conceptual-model scope Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…cies CRITICAL fixes: - contributor/overview: remove fabricated "four dimensions" claim - user/overview: GitHub sign-in only (Keycloak has no GitLab IdP) - user/overview: remove "team competitions" (doesn't exist) - conceptual-model: artifact entity qualified as "currently: PRs, issues, reviews, comments" not thesis chapters/design mockups - conceptual-model: "55 event types" (exact count, not "55+") HIGH fixes: - getting-started: remove phantom "Help & Feedback button in footer" - getting-started: add missing nav items (Profile, Teams) - user/overview: "team roles" → "workspace roles" - README: qualify GitHub/GitLab integration asymmetry - AboutMissionSection: remove AI Mentor from wrong feature card - ai-mentor: "reduces stress" → "helps structure" (unverified claim) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
FelixTJDietrich
changed the title
FelixTJDietrich
changed the title
The PracticeFindingTargetType enum→String refactor from #953 changed the DTO serialization but the OpenAPI spec was not regenerated. CI correctly caught the drift. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…illars - user/leaderboard: drop "and Gamification" title, soften competition framing - conceptual-model: replace "Observe→Detect→Guide→Grow" pipeline claim with honest lifecycle prose; mark Guidance as Planned (currently embedded in PracticeFinding/ChatMessage); remove brittle "55 event types" count; add explicit Engagement & Recognition note (projections over the Event ledger, activity-shaped today, practice-shaped is on the roadmap) - system-design: drop legacy gamification SVGs and half-reframed prose; point at the canonical conceptual-model for architecture; keep only workflow-level diagrams that complement it; delete five orphaned SVGs - README: collapse 4 features → trio (Practice Detection / Adaptive Coaching / Engagement & Recognition); fold AI Mentor into coaching; move Agent Orchestration into an "Implementation notes" section; rewrite roadmap with practice-aware recognition as the headline item - landing/about/homepage: align E&R copy to "surface contribution activity over time" (not "make practices visible"); fold AI mentor into Adaptive Coaching consistently; tighten FAQ with practice-focused questions (what makes a good practice, adaptive coaching, LLM data flow) - docusaurus.config: drop "Cognitive Apprenticeship" keyword (no longer user-facing surface; remains as internal CaMethod implementation detail) - domain-model.hyl: update header comment from "pipeline" to "lifecycle" - about hero: add anchor link to conceptual model Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Ground-up redesign of marketing and conceptual surfaces around the practice-aware feedback loop. Three pillars (Practice Detection / Adaptive Coaching / Engagement & Recognition) collapse into one closed loop — Detect → Coach → Reflect — backed by domain entities and four feedback channels (in-context, reflection dashboard, conversational mentor, facilitator dashboard). Domain model (8 entities, +Channel, +Contestation) - Workspace, Contributor, Artifact, Event, Practice, Finding, Channel, Contestation. Guidance folded into Finding (text + planned recommendedAction) and Channel (delivery semantics). - Channel marked <<planned>> as first-class entity; today routing logic lives in DiffNotePoster, mentor handlers, and webapp routes. - Contestation surfaces FindingFeedback under its thesis name. - New practice-loop.hyl: conceptual flow events → detection → findings → four channels → contributor/facilitator, with contestation backflow. Conceptual-model rewrite - New entity table + four-channel routing table aligned to feedback levels. - Codebase-mapping table updated; Channel marked Planned, Guidance dropped. - Architecture section split into deployment view + practice-aware loop. - Beyond-SE speculative table removed. Landing rebuild - Hero: leaderboard preview replaced with a sample finding card (practice + verdict + evidence + recommended action). - Features: Detect → Coach → Reflect pipeline replacing the trio. - Why-choose: sharpened wedge "Practice findings, not scores". - FAQ: practice-first questions including explicit "why no leaderboard?", "is this a coding agent?", "is this a review bot?", "surveillance?". About rebuild - Five sections: problem, method, three commitments (formative, autonomy-supportive, no surveillance), honest limitations, open/academic. - FeatureCard.tsx + stories deleted (no remaining consumers). README rewrite - "What this is not" under the tagline. - Detect/Coach/Reflect narrative; deployment shape paragraph. - Semester-horizon roadmap with practice-aware recognition replacing legacy scoring; legacy XP/league surfaces slated for sunset. Mentor framing - Public surfaces reference the "conversational mentor" (channel role), not "Heph the AI mentor" (UI metaphor). Heph stays in user docs. - "A reflection partner, not a coding agent" appears across FAQ, About, and README — futureproofs the surface against channel evolution. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Public copy was defining Hephaestus by what it is not — leaderboard,
defect-bot, coding agent, surveillance, ranking. That posture was
defensive. Confident product copy describes what the platform is and
lets the absences speak for themselves.
- README: "What this is not" section removed; Reflect description loses
"built for coaching, not grading" and "never the headline".
- LandingHeroSection: anti-pattern subhead and outline-Badge removed; H1
is now "Practice-aware feedback for every contribution"; finding-card
drops the "about the work, not the worker" caption and gains a "React"
label on the action row.
- LandingWhyChooseSection: rewritten without the analytics/diff-bot
contrast. Headline "Findings tied to evidence and an action."
Differentiators describe what detection reads and how findings reach
people, not what other tools fail to do.
- LandingFeaturesSection: "Reflect" stage no longer says "never public
ranking" or "opt-in, never the headline"; "Coach" stage drops the
"not a coding agent" parenthetical; "Detect" stage drops "not a
vendor prompt".
- LandingFAQSection: dropped four defensive Q&As ("why no leaderboard?",
"is this a coding agent?", "is this a review bot?", "surveillance?").
Added a positive "Where do findings actually appear?" channel question.
- AboutMissionSection: commitments rephrased as positive design choices
("Formative feedback", "Autonomy-supportive delivery", "Asymmetric
scoping") instead of "What we will not do" framing. Honest-limitations
alert renamed to "What's next" with positive forward-looking copy.
Problem section keeps the practice/feedback observation but drops the
"bots fill silence with noise; analytics tools fill it with scores"
swipe.
- AboutHeroSection: tagline drops "where no human is available".
- HomepageFeatures (docs): mirrors landing — Reflect title becomes
"Private surfaces for patterns over time"; Coach drops "not a coding
agent"; Detect drops "vendor prompts"; copy aligned across surfaces.
- docs/user/overview, getting-started, leaderboard: drop "never public
ranking", "not a coding agent", "not a ranking", "remain the primary
signal of contribution quality" — rephrase positively.
- conceptual-model: drop "never the object of ranking" from Contributor;
drop "There is no public ranking, by design" from the channel
description; drop "not just stored" from Contestation. Asymmetric
scoping is described as a positive choice.
The thesis stands on its own terms: practice-aware feedback delivered
through coupled channels. The negations were carrying weight the
positive copy can carry better.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Stripped marketing scaffolding (badges-as-headers, pipeline arrows,
verb-stage decorations, theory citations, jargon nouns: "practice-aware
loop", "coupled channels", "unit of value", "track record per practice",
"versioned, inspectable practice catalog"). Rewrote everything in
direct, conversational prose.
Hero
- H1: "Better feedback on every pull request."
- Subhead names what a person experiences ("tells the contributor —
clearly, with examples — what to do next") rather than the system's
mechanism.
- Sample card simplified to a quoted Hephaestus comment, no pills, no
severity colour, no action-row chips.
Features
- Replaced the Detect → Coach → Reflect three-card pipeline with four
short paragraphs ("Your standards, written down.", "Comments where
the work is.", "A mentor when you want to think out loud.", "A quiet
place to look back.").
- Heading: "How it fits into the day."
Why-choose
- Replaced the three-icon-grid with two paragraphs of prose.
- Heading: "Coaching that meets the contributor where they are."
FAQ
- Heading: "Questions."
- Six short Q&As written like a colleague answering — no defensive
framing, no theory citations.
About
- Hero: one sentence.
- Mission: three sections of prose ("Why we built it.", "How it talks
to people.", "Open, and made for tinkering."). No commitments grid,
no alert callout, no separators-as-decoration.
README
- Plain pitch + plain "How it works" prose.
- Roadmap rewritten as bullet sentences without horizon labels or
process meta. The work is the point.
Docs (HomepageFeatures, user overview, getting-started, leaderboard,
conceptual-model)
- Same voice. Tables stay where they're reference; prose around them
is direct. Conceptual-model entity descriptions read as plain English.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Three corrections asked for + a fourth surfaced by a reality audit
against shipping code.
Honest framing
- Hero H1 names practices, not pull requests: "Feedback on the
practices behind the code." Subhead drops "tells the contributor
what to do next" — the artifact (a comment) is the subject; the
reader takes what fits.
- README intro reframed around "practice-aware feedback in software
project work." Implementation-detail paragraph (Spring Boot + TS
service + sandboxed agent + Keycloak) removed from public surface.
- "Works with GitHub and GitLab" replaces the apologetic GitLab
qualifier — both providers ship review delivery today.
- "model provider" → "AI model provider" everywhere it appears in
user-facing copy.
Cut overclaims
- Drop the fictional "quiet place to look back / trending practices"
feature stage from landing and docs. The profile shows review
activity and XP; practice trending isn't built yet.
- Drop "Aggregate views exist… never to rank people" from About.
Today's aggregate view is a leaderboard.
- Drop "Mark it as taken on / push back / not relevant" from user
overview. The API exists; the UI doesn't.
- "Edit it any time" / "list of practices is yours to write" → "yours
to define — today by editing seed data, soon through an in-app
editor."
Channel-table honesty
- Conceptual-model channels table gains a Status column. In-context
and Conversation marked Today; Reflection marked "Today: profile;
Planned: findings reflection"; Overview marked Planned.
- Contestation row marked "Backend done; in-app UI coming."
Voice
- Subject of every user-facing sentence is the artifact ("a comment
appears…") or the contributor ("take what fits, push back on what
doesn't") — never Hephaestus reading/writing/saying/telling.
- Drop "coaching that meets the contributor where they are."
- Drop "patient, specific, with examples when they help" self-praise.
- Drop "we write Hephaestus the way a thoughtful colleague would."
- Why-Choose H2 → "Findings tied to evidence and a next move."
- Drop "Same place, more useful" comparative.
Roadmap
- README: explicit roadmap items for the reflection dashboard, in-app
contestation UI, the practice-list editor, practice-aware
recognition replacing activity-shaped scoring.
Rebase
- A clean rebase onto origin/main was attempted and aborted: the
shallow worktree's history doesn't share a deep enough ancestor
with main, and the user already chose to keep deleted DSMS / legal
/ achievements docs (which are exactly what the missing-from-branch
commits re-add). PR review will resolve any remaining drift.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
The diagram had two boxes that didn't correspond to JPA entities: - Channel was a typology, not a row. The four channels are kinds of delivery, not instances; cardinality fixed by design. - Contestation was a reaction event borrowing a thesis name in place of the actual JPA type FindingFeedback. Six entities now, every one of them backed by a live JPA entity: Workspace, Contributor, Artifact, Event, Practice, Finding. The terminal flow is a "delivered to" arrow from Finding to Contributor — the loop closes without inventing a box. Conceptual-model page reshaped to match. Channels typology + four-row Status table dropped. Codebase mapping reduced to six rows. A short sentence after the table notes that finding guidance text is delivered as a comment, and FindingFeedback records a contributor's reaction. practice-loop.hyl deleted: it depended on the four-channel framing the domain model no longer carries. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Two label moves on the conceptual diagram. The codebase doesn't change. - Workspace → Project on the diagram. The project is the endeavor; the workspace is its container in code. The mapping table notes that a Project is `Workspace` (with one or more `Repository` rows underneath). - Event → Contribution. The diagram now reads "contributors make contributions" instead of "perform events", which is what we mean. Code keeps `ActivityEvent`; the mapping table calls it out. The conceptual-model page gains a one-line note that the diagram uses conceptual names while the schema uses Hephaestus-specific names — they map 1:1. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Six entities, eleven relationships, all defensible from main.tex. Methods read as use-case responsibilities, not Java methods: - Project: enrol(contributor), definePractice, retirePractice - Contributor: contribute, react(finding) - Practice: detect(contributions), explain - Artifact, Contribution, Finding carry no methods (they're records, not actors). Attribute trims (only domain-significant attributes survive): - Project: slug, displayName (status removed — operational, not domain) - Artifact: kind, title (lifecycleState removed — single-table-inheritance leak) - Contribution: kind, occurredAt - Practice: slug, name, category (triggerEvents and detectionPrompt removed — the trigger semantics is now a relationship; the prompt is a configuration value, not a domain attribute) - Finding: verdict, severity, confidence, evidence, guidance (reasoning removed — overlaps evidence/guidance for diagram audience) Relationship rework: - Drop "Finding evaluates Artifact" — the proposal does not predicate findings on artifacts. A finding is about a contributor's practice, not about an artifact. The artifact is the substrate on which contributions happen; findings reach artifacts transitively through the contributions they cite. - Add "Finding cites Contribution" (1..* — *). The proposal: findings are "tied to evidence cues" — these point to contributions. - Add "Contributor reacts to Finding" (* — *). The proposal's RQ3 hinges on what contributors act on, ignore, or contest. - Rename "Practice triggers on Contribution" → "Practice requires Contribution". Proposal verbatim uses "required event types". - Rename "Contribution shapes Artifact" → "Contribution on Artifact". Less active; covers status checks and other non-modifying contributions. - Rename "Finding delivered to Contributor" → "Finding about Contributor". Structural truth (whose practice) over operational truth (where it lands). - Complete cardinalities — every association labelled on both ends where it carries information. Conceptual-model page reshaped to match: explicit relationships table, short note that artifacts are substrate not subject, mapping table unchanged. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
User-provided layout improvements: tightened label positions, nudged Practice and Finding arrows for cleaner geometry, repositioned the 'about' and 'reacts to' arrows so they don't crash through other nodes. Also drops the 'Practice requires Contribution' arrow. The trigger relationship is implicit in detection — a Practice's detect() method takes contributions as input, and the proposal's "required event types" is a configuration concern of the practice-definition format, not a structural domain relationship that needs its own arrow. Diagram is calmer with ten relationships instead of eleven. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
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
Ground-up redesign of the public-facing surfaces around the practice-aware feedback loop. Replaces the previous slogan-and-feature-pillars framing with a domain-model-anchored narrative: Detect → Coach → Reflect, backed by eight entities and four feedback channels. Also includes the server-side
PracticeFindingTargetTypeenum →Stringrefactor from the main rebase (#953).The redesign treats every visible surface as a single coherent message: hero, landing features, why-choose, FAQ, about, README, conceptual model, HyLiMo diagrams, user/contributor docs.
Domain model — 8 entities
Workspace, Contributor, Artifact, Event, Practice, Finding, Channel, Contestation.Channelis the design contribution: in-context push, reflection-dashboard pull, conversational-mentor dialogic, facilitator-dashboard educator. Marked<<planned>>as a first-class entity; routing logic lives today inDiffNotePoster, mentor handlers, and webapp routes.ContestationsurfacesFindingFeedbackunder its thesis name (RQ3 measurement signal).Guidanceentity is folded intoFinding(text + plannedrecommendedAction) andChannel(delivery semantics).New diagram
docs/diagrams/practice-loop.hyl— the conceptual flow the deployment view doesn't show: events → detection → findings → four channels → contributor/facilitator, with contestation backflow. Rendered topractice-loop.svg.Conceptual-model rewrite
Channelmarked Planned,Guidancedropped, all other rows verified against current JPA entities.Landing redesign
LeaderboardTableimport). Replaced with a self-contained sample finding card: practice + verdict + evidence + recommended action + confirm/dispute/dismiss actions. The unit of value is now the unit on the hero. Subhead under the H1: "Not a leaderboard. Not a defect-catching review bot. A coaching layer that turns review activity into feedback contributors actually use."Practice Detection / Adaptive Coaching / Engagement & Recognitiontrio replaced with Detect → Coach → Reflect pipeline. Each card is anchored to domain entities and channels with three concrete bullets. Pipeline arrows visible on desktop.About redesign
Five sections in order: the problem → our approach (method) → three commitments (formative-not-evaluative, autonomy-supportive, no-surveillance) → honest limitations → open and academic. The page no longer duplicates the landing trio — it carries the why the landing carries the what.
webapp/src/components/info/about/FeatureCard.tsxand its story removed (no remaining consumers).README rewrite
Agent Orchestrationremoved from the headline trio (lives in implementation notes / contributor docs only).Mentor framing — futureproofed
Engagement & Recognition — demoted, not deleted
No longer a marketing pillar. The Reflect stage acknowledges optional weekly activity recognition — workspaces opt in. Practice-aware recognition is the next-step roadmap item; legacy XP/league/achievement surfaces are explicitly slated for sunset.
Server changes (from main rebase, #953)
PracticeFindingTargetTypeenum deleted →Stringfield with CHECK constraint.TargetTypeTestsremoved (enum no longer exists).How to test
npm run check:webapp✅ Biome clean across 400 filesnpm run typecheck:webapp✅npm run test:webapp✅ 68/68npm run check:intelligence-service✅npm run check:webhook-ingest✅npm run typecheck:scripts✅cd docs && npm run build✅npm run docs:render-diagramsregenerates all three SVGs (HyLiMo CLI is non-deterministic — see Known limitations)LeaderboardTableimport or mock contributor data on any landing surfaceKnown limitations (deferred to follow-ups)
PracticeFindingController,FindingFeedbackController,PracticeCatalogController(PRs feat(server): practice CRUD API #885, feat(server): add practice findings REST API for contributor dashboard #910, feat(server): finding feedback entity and API for contributor reactions #911) — the next webapp PR consumes them.Gamification/XpSystem/LeaguePoints/CaMethodidentifiers persist in the codebase. The reframe is at the documentation/UI layer; renaming or retiring scoring infrastructure is structural work tracked separately.docs/diagrams/*.svgis committed alongsidedocs/static/img/diagrams/*.svg(Docusaurus needs the static copy). Deduplication is a future improvement.🤖 Generated with Claude Code