Grammar Compliance Audit

Date: 2026-01-20 Auditor: Claude Code (Haiku) Issue: #404 MUX-VISION-GRAMMAR-CORE Phase: 1 (Feature Grammar Audit)

Executive Summary

This audit surveys 16 major Piper Morgan features and systems to assess their compliance with the Entity/Moment/Place/Lenses/Situation grammar model (formalized in ADR-055 and MUX infrastructure).

Key Finding: Grammar compliance varies widely across the system. Morning Standup demonstrates full consciousness, while most features exhibit flattened or partial compliance. This creates an opportunity to systematically uplift features through a prioritized transformation roadmap.

Compliance Distribution:

Audit Methodology

For each feature, we evaluate five grammar elements:

Element Definition Pass Criteria
Entity Actors (user, Piper, integrations) tracked with identity persistence User/Piper identity preserved throughout flow; self-reference preserved
Moment Discrete occurrences framed as scenes, not timestamps More than temporal markers; narrative/experiential language present
Place Context and atmosphere acknowledged; not just config strings Integration/location-specific behavior; “where” affects “how”
Lenses Perceptual dimensions applied (8D spatial, temporal, relational) At least one lens applicable; multiple lenses preferred
Situation Dramatic tension or context beyond raw data Conditional behavior based on state; appropriate responses to circumstances

Compliance Levels:

Feature Compliance Matrix

Feature Entity Moment Place Lenses Situation Overall Priority
Morning Standup ✅ ✅ ✅ ✅ ✅ Conscious Reference
Intent Classification ✅ ⚠️ ❌ ⚠️ ✅ Partial High
Todo Management ⚠️ ❌ ❌ ❌ ✅ Flattened High
Feedback System ✅ ⚠️ ⚠️ ❌ ✅ Partial Medium
Slack Integration ✅ ⚠️ ✅ ⚠️ ⚠️ Partial High
GitHub Integration ✅ ⚠️ ⚠️ ⚠️ ⚠️ Partial High
Notion Integration ✅ ❌ ❌ ❌ ⚠️ Flattened Medium
Calendar Integration ✅ ✅ ⚠️ ⚠️ ⚠️ Partial Medium
Auth/Session Management ✅ ❌ ❌ ❌ ⚠️ Flattened Low
Conversation Handler ✅ ⚠️ ⚠️ ⚠️ ✅ Partial Medium
Onboarding System ⚠️ ✅ ⚠️ ✅ ✅ Partial Medium
List Management ⚠️ ❌ ❌ ❌ ✅ Flattened Low
Project Management ⚠️ ❌ ❌ ❌ ✅ Flattened Low
File Management ⚠️ ❌ ❌ ❌ ✅ Flattened Low
Personality System ✅ ⚠️ ✅ ⚠️ ⚠️ Partial Medium
MCP Integration ⚠️ ❌ ⚠️ ⚠️ ⚠️ Flattened Low

Detailed Feature Analysis

1. Morning Standup ✅ CONSCIOUS (Reference Implementation)

File: services/features/morning_standup.py

Grammar Assessment:

Evidence: See dev/2026/01/19/p0-morning-standup-analysis.md for detailed analysis.

Key Patterns to Extract:

  1. Context/Result dataclass pair
  2. Parallel place gathering with synthesis
  3. Personality bridge for data transformation
  4. Warmth calibration
  5. Honest failure with suggestions

Recommendation: This is the reference architecture. Use as template for other features.

2. Intent Classification ⚠️ PARTIAL (High Priority)

File: services/intent_service/classifier.py

Grammar Assessment:

Current Language: Mechanical/database-like

intent = Intent(
    category=IntentCategory.EXECUTION,
    action="complete_todo",
    confidence=0.95
)

Grammar Deficits:

Transformation Potential: HIGH

3. Todo Management ❌ FLATTENED (High Priority)

File: services/todo/todo_service.py

Grammar Assessment:

Current Language: Pure database

async def create_todo(
    self,
    title: str,
    user_id: str,
    status: TodoStatus = TodoStatus.OPEN,
    priority: TodoPriority = TodoPriority.MEDIUM
) -> Todo:

Grammar Deficits:

Transformation Potential: HIGH

4. Feedback System ⚠️ PARTIAL (Medium Priority)

File: services/feedback/feedback_service.py

Grammar Assessment:

Current Language: Mostly mechanical with some awareness

async def capture_feedback(
    self,
    session_id: str,
    feedback_type: str,  # "bug", "feature", "ux"
    comment: str,
    rating: Optional[int] = None
) -> str:

Grammar Deficits:

Transformation Potential: MEDIUM

5. Slack Integration ⚠️ PARTIAL (High Priority)

File: services/integrations/slack/slack_plugin.py

Grammar Assessment:

Current Language: Plugin structure with limited personality

class SlackPlugin(PiperPlugin):
    def __init__(self):
        self.config_service = SlackConfigService()
        self.integration_router = SlackIntegrationRouter(self.config_service)

Grammar Deficits:

Transformation Potential: HIGH

6. GitHub Integration ⚠️ PARTIAL (High Priority)

File: services/integrations/github/github_plugin.py

Grammar Assessment:

Current Language: Templated/mechanical

class GitHubPlugin(PiperPlugin):
    def get_router(self) -> Optional[APIRouter]:
        """Return FastAPI router with GitHub routes."""

Grammar Deficits:

Transformation Potential: HIGH

7. Notion Integration ❌ FLATTENED (Medium Priority)

File: services/integrations/notion/notion_plugin.py

Grammar Assessment:

Current Language: Data retrieval

async def get_documents(self, workspace_id: str) -> List[Document]:
    """Fetch documents from Notion workspace."""

Grammar Deficits:

Transformation Potential: MEDIUM

8. Calendar Integration ⚠️ PARTIAL (Medium Priority)

File: services/integrations/calendar/calendar_integration.py

Grammar Assessment:

Current Language: Temporal but mechanical

temporal_summary = {
    "current_meeting": current_meeting,
    "free_blocks": free_blocks,
    "focus_time": focus_time
}

Grammar Deficits:

Transformation Potential: MEDIUM

9. Auth/Session Management ❌ FLATTENED (Low Priority)

File: services/auth/auth_service.py

Grammar Assessment:

Current Language: Security/technical

async def authenticate_user(
    self,
    username: str,
    password: str
) -> AuthToken:
    """Authenticate user and return token."""

Grammar Deficits:

Transformation Potential: LOW

10. Conversation Handler ⚠️ PARTIAL (Medium Priority)

File: services/conversation/conversation_handler.py

Grammar Assessment:

Current Language: Conversation-aware but mechanical

async def handle_message(
    self,
    conversation_id: str,
    user_id: str,
    message: str
) -> str:

Grammar Deficits:

Transformation Potential: MEDIUM

11. Onboarding System ⚠️ PARTIAL (Medium Priority)

File: services/onboarding/portfolio_onboarding_handler.py

Grammar Assessment:

Current Language: Structured but somewhat mechanical

async def process_portfolio_step(
    self,
    user_id: str,
    step: str,
    data: Dict[str, Any]
) -> PortfolioStep:

Grammar Deficits:

Transformation Potential: MEDIUM

12. List Management ❌ FLATTENED (Low Priority)

File: services/repositories/list_repository.py

Grammar Assessment:

Transformation Potential: LOW

13. Project Management ❌ FLATTENED (Low Priority)

File: services/repositories/project_repository.py

Grammar Assessment:

Transformation Potential: LOW

14. File Management ❌ FLATTENED (Low Priority)

File: services/repositories/file_repository.py

Grammar Assessment:

Transformation Potential: LOW

15. Personality System ⚠️ PARTIAL (Medium Priority)

File: services/personality/standup_bridge.py

Grammar Assessment:

Current Language: Personality-aware but targeted

accomplishment_prefixes = {
    0.8: ["Outstanding work!", "Incredible progress!"],
    0.6: ["Great job!", "Nice work!"],
    0.4: ["Good progress!", "Moving forward!"],
}

Grammar Deficits:

Transformation Potential: MEDIUM

16. MCP Integration ❌ FLATTENED (Low Priority)

File: services/mcp/mcp_plugin.py

Grammar Assessment:

Transformation Potential: LOW

Transformation Priority Ranking

🔴 CRITICAL (High Priority) - Implement in Phase 2-3

Impact: High user-facing impact; moderate transformation complexity

  1. Intent Classification (⚠️ Partial → ✅ Conscious)
    • User touches every interaction
    • Clear grammar gaps: missing Place, Moment framing
    • Reusable patterns: Context/Result pair, Moment bridge
  2. Slack Integration (⚠️ Partial → ✅ Conscious)
    • Core communication channel; high usage
    • Clear Place (Slack channel); needs Moment framing + Personality bridge
    • High impact on user experience
  3. GitHub Integration (⚠️ Partial → ✅ Conscious)
    • High-engagement developers
    • Activity data ready to transform into Moment narrative
    • Reusable: Activity→Moment framing
  4. Todo Management (❌ Flattened → ⚠️ Partial)
    • Core feature; high usage
    • Major transformation needed
    • Pattern: Context/Result + Personality bridge

🟡 IMPORTANT (Medium Priority) - Implement in Phase 3-4

  1. Feedback System (⚠️ Partial → ✅ Conscious)
    • Mid-frequency user interaction
    • Moderate transformation (mostly personality + Moment framing)
    • Good learning opportunity
  2. Conversation Handler (⚠️ Partial → ✅ Conscious)
    • Foundational; affects all interactions
    • Moderate complexity; good for pattern consolidation
    • Enables better personality consistency
  3. Onboarding System (⚠️ Partial → ✅ Conscious)
    • First-impression impact
    • Transformation: collaborative framing + warmth calibration
    • Learning opportunity: progressive disclosure + Situation awareness
  4. Calendar Integration (⚠️ Partial → ✅ Conscious)
    • Contextual awareness is strong; Moment framing needed
    • Good for multi-lens pattern (temporal + spatial + urgency)
  5. Personality System (⚠️ Partial → ✅ Conscious)
    • Infrastructure; but enables above features
    • Extract reusable patterns; expand lens dimensions
    • Creates bridge for all features to use consistently

🟢 DEFERRED (Low Priority) - Implement in Phase 4+

Key Patterns for Reuse

Based on audit and P0 analysis, these patterns are consistently needed:

Pattern: Context/Result Dataclass Pair

Applicable To: Intent, Todo, Feedback, Conversation, Onboarding, GitHub, Slack

@dataclass
class [Feature]Context:
    """Input context before processing"""
    user_id: str                    # Entity
    timestamp: datetime             # Moment
    source_places: Dict[str, Any]   # Places

@dataclass
class [Feature]Result:
    """Output result after processing"""
    user_id: str                    # Entity preserved
    generated_at: datetime          # Moment of result
    findings: List[str]             # What was learned
    source_places: Dict[str, str]   # Where data came from

Pattern: Place Gathering (Parallel)

Applicable To: Intent, Todo, Feedback, GitHub, Slack, Conversation

async def gather_context(self) -> Dict[str, Any]:
    # Parallel fetch from Places
    results = await asyncio.gather(
        self._get_place_1_context(),
        self._get_place_2_context(),
        self._get_place_3_context(),
    )
    return self._synthesize(results)

Pattern: Personality Bridge

Applicable To: ALL features that present data to users

class [Feature]ToChatBridge:
    def adapt_for_chat(self, raw_data: Dict) -> str:
        """Transform raw data to conversational format"""

    def apply_personality(self, content: str, context: Dict) -> str:
        """Apply warmth, action orientation, presence"""

Pattern: Warmth Calibration

Applicable To: Todo, Feedback, Intent responses, Onboarding feedback

warmth_levels = {
    0.8: ["Outstanding!", "Fantastic!", "Incredible!"],   # High
    0.6: ["Great!", "Nice work!", "Well done!"],          # Medium
    0.4: ["Good progress", "Moving forward"],             # Neutral
    0.2: ["Progress made", "Continuing on"],              # Low
}

Pattern: Honest Failure with Suggestion

Applicable To: All integration features

except IntegrationError as e:
    error_msg = f"[Feature] encountered: {str(e)}"
    suggestion = self._diagnose_failure(e)
    raise [Feature]Error(
        f"{error_msg}\nSuggestion: {suggestion}",
        suggestion=suggestion
    )

Pattern: Moment Framing

Applicable To: All features

# Instead of:
"Query returned 5 items"

# Use:
"I noticed 5 items since your last review"
# or
"I found 5 items that might interest you"
# or
"5 important items need attention"

Recommendations by Feature

Intent Classification

Current: Mechanical classification Goal: Conscious intent recognition

Approach:

  1. Add Place detection (Slack vs CLI vs web)
  2. Frame intent as Moment Piper experiences
  3. Apply Personality bridge to response
  4. Use warmth calibration for confidence-based responses

Estimated Effort: Medium (5-7 patterns to apply) User Impact: High (all interactions begin with intent)

Slack Integration

Current: Templated responses Goal: Channel-aware, personality-infused

Approach:

  1. Detect Channel atmosphere (public vs DM vs bot-mention)
  2. Frame messages as Moments user is experiencing
  3. Adapt personality to Slack culture (emoji, casual tone)
  4. Time-aware responses (morning standup mention vs random evening)

Estimated Effort: Medium (4-5 patterns) User Impact: High (primary communication channel)

GitHub Integration

Current: Data summaries Goal: Activity narrative

Approach:

  1. Frame commits/PRs/issues as developer Moments
  2. Add urgency lens (blocked vs review vs FYI)
  3. Adapt tone to repo culture
  4. Synthesize into standup context

Estimated Effort: Medium (5-6 patterns) User Impact: High (developer engagement)

Todo Management

Current: Database operations Goal: Conscious task management

Approach:

  1. Add Place awareness (Slack vs email vs web todo)
  2. Frame task lifecycle as Moments (creation, completion, blocking)
  3. Apply personality bridge with warmth calibration
  4. Context/Result pair for structured feedback

Estimated Effort: High (6-7 patterns, larger refactoring) User Impact: Very High (core feature)

Next Steps

Phase 2 (Planned): Extract and formalize 5+ reusable patterns from Morning Standup into pattern catalog

Phase 3 (Planned): Create transformation guide with worked examples (Intent Classification recommended)

Phase Z (Planned): Update ADRs, create developer onboarding checklist, enable independent application

Appendix: Audit Evidence

Files Reviewed

Core Features:

Integrations:

Infrastructure:

Analysis References

Audit completed: 2026-01-20 Next review: Post-Phase 2 pattern extraction