Knowledge Sharing Patterns: The Human Shadow Model

by SLV Team 51 views
Knowledge Sharing Patterns: The Human Shadow Model

Hey guys! Let's dive into something super important for any team, especially when you're working with AI agents: knowledge sharing. It's all about figuring out what information to broadcast and what to keep close to the vest. Think of it like a human developer: we've got our public code, shared knowledge, and then all the nitty-gritty details we keep in our own little workspace. This article will break down a "Human Shadow Model" for your agent worktrees, making sure everyone's on the same page. This model will helps you organize your project with the human developers. It is based on the Cat-Lab experience.

The Human Shadow Model: Knowledge Division

So, what's the deal with this "Human Shadow Model"? Simple: it mirrors how human developers operate. We've got two main categories of knowledge:

  • Generic Knowledge (Shared): This is the stuff everyone needs to know. It's the core principles, the best practices, the architectural decisions that shape your project. This is the stuff that gets tracked, shared, and versioned. Make it public.
  • Specific Knowledge (Shadow/Private): This is the behind-the-scenes stuff. Your work-in-progress notes, your debug logs, those half-baked ideas you're still kicking around. It's the stuff that's essential for your work, but might not be relevant to everyone else. The model helps you organize those private notes.

The Human Shadow Model in a Nutshell

  • Like Humans: Just like human developers, agents also have a shadow. They have their own notes, drafts, and experiments. They share final code and key insights. They help teammates when asked. They keep detailed processes private, but not hidden.

Let's get into the details.

Generic Knowledge: The Shared Treasure

Okay, let's talk about that generic knowledge, the shared stuff. This is the information you want everyone to have access to. It's the stuff that makes your team tick. How do we share that?

  • Location: The place where everyone can access the stuff. Put the documentation, the lesson learned in a public place. Tracked in git, accessible to all.

    • Patterns Learned: LESSON_LEARNED.md. Think of this as your team's collective wisdom. Any time you learn a cool new trick, a valuable insight, or a pattern that's worth sharing, write it down here. It's like a knowledge base for your entire team.
    • Architecture Decisions: docs/architecture/. Any significant design choices, architectural principles, or high-level overviews of your system go here. It's the blueprint of your project.
    • Workflows: CONTRIBUTING.md. This is where you document the standard procedures for contributing to your project. How do you submit a pull request? What's the code style? What are the testing procedures? Make it easy for everyone to get involved.
    • Retrospectives: retrospectives/. After each sprint or project phase, have a retrospective. What went well? What could be improved? Document it here.
    • Issue Discussions: GitHub issues. Use issues to discuss features, bugs, and other topics. This ensures everyone's on the same page.
    • Code: src/ (via PRs). The heart of your project! All the code goes here, but it's shared via pull requests (PRs). This lets everyone review the changes.

  • Examples

    • "git -C pattern works well for sync". This is a handy git trick everyone should know.
    • "Free will model better than rigid roles". Important architectural insight.
    • "Always create planning issue before large changes". A smart workflow tip.

The Importance of Sharing

  • Share: Final work (via PRs). Generic lessons (via LESSON_LEARNED.md). Architecture decisions (via docs). When someone asks for help (context sharing).

Specific Knowledge: Your Agent's Private Domain

Now, let's talk about the specific knowledge, your agent's private domain. This is the stuff that's not ready for prime time. It's work in progress, experimental notes, and temporary logs. It's important for you, but not necessarily for everyone else. This is where the shadow comes in, the private working area.

  • Location: This is the place where you put your private stuff. Gitignored, agent-specific.

    • WIP notes: agents/N/.tmp/. Work in progress, temporary. This is for all those notes, ideas, and experiments you're working on. It's the agent's scratchpad.
    • Research explorations: agents/N/.notes/. Keep all the exploration and research documentation here.
    • Debugging logs. Debugging logs are often specific to a particular issue or context.
    • Draft ideas before ready to share. Draft ideas are not ready for public consumption.
    • Personal context for current work. Your private context.

  • Examples

    • "Tried 5 different approaches, this one works best" (detailed notes). This is where you document your thought process and the reasoning behind your decisions. It's your private log of experiments.
    • "Debug log from failed attempt" (temporary). Keep this around while debugging, then delete it.
    • "Half-baked idea to explore later" (draft). Jot down those ideas you want to revisit later. Your future self will thank you.

What to Keep Private

  • Keep Private: Detailed explorations (unless asked). Failed experiments (unless lesson learned). Personal notes (your workspace). Work in progress (until ready).

Sharing Philosophy: The Art of the Reveal

So, when do you share and when do you keep it private? Here's the general philosophy:

The Art of Sharing

  • Final work: When your work is done and ready to be shared, share it through pull requests. This is how you contribute to the shared code base.
  • Generic lessons: When you discover a pattern or insight that could benefit the whole team, add it to LESSON_LEARNED.md.
  • Architecture decisions: Document any architectural decisions in the appropriate documentation.
  • Help when asked: If a teammate asks for help, don't be afraid to share your specific knowledge to help them understand. Context sharing is key.

The Privacy Zone

  • Detailed explorations: Keep your detailed explorations private unless someone specifically asks.
  • Failed experiments: If an experiment fails, that's fine. Don't share the details unless there's a valuable lesson learned.
  • Personal notes: Your personal notes are for your eyes only. Your workspace is your sanctuary.
  • Work in progress: Keep your work in progress private until it's ready to be shared.

File Organization Example: Structure for Success

Here's how a well-organized project might look. This is a practical example of the file organization.

Cat-Lab/
├── LESSON\_LEARNED.md # Shared: patterns everyone learns from
├── docs/ # Shared: architecture, guides
├── src/ # Shared: code (via PRs)
├── CONTRIBUTING.md # Shared: how we work
├── agents/
│ ├── 1/
│ │ ├── .tmp/ # Private: Agent 1 temporary work
│ │ ├── .notes/ # Private: Agent 1 persistent notes
│ │ └── src/ # Shared when PR merged
│ ├── 2/
│ │ ├── .tmp/ # Private: Agent 2 temporary work
│ │ ├── .notes/ # Private: Agent 2 persistent notes
│ │ └── src/ # Shared when PR merged

Detailed Explanation

  • LESSON_LEARNED.md: This file is where everyone can learn new patterns and lessons.
  • docs/: Documentation is shared here. Architecture, guides, etc.
  • src/: Source code. Shared via pull requests.
  • CONTRIBUTING.md: How we work. Everyone can read it.
  • agents/: Agents directory.
    • 1/: Agent 1 specific directory.
      • .tmp/: Agent 1 temporary work. Private.
      • .notes/: Agent 1 persistent notes. Private.
      • src/: Code that will be merged via pull requests.
    • 2/: Agent 2 directory.
      • .tmp/: Agent 2 temporary work. Private.
      • .notes/: Agent 2 persistent notes. Private.
      • src/: Code that will be merged via pull requests.

This structure helps everyone know where to look for information and keeps the private stuff out of the way.

.gitignore: Keeping it Clean

To make sure your private stuff stays private, you'll need a good .gitignore file. Here's a quick example:

# Private agent knowledge (shadow)
agents/*/.tmp/*
agents/*/.notes/*
!agents/*/.tmp/README.md
!agents/*/.notes/README.md

Explanation

  • **agents/*/.tmp/
  • agents/*/.notes/: These lines tell git to ignore everything in the .tmp/ and .notes/ directories for all agents. This is where you put your private notes.
  • **!agents/*/.tmp/README.md
  • !agents/*/.notes/README.md: The ! means that you do want to share this. This allows you to include a README file in the .tmp and .notes directories. These are useful for describing the purpose of those directories.

This setup keeps your private stuff out of the public repo.

Benefits: Why This Matters

So, what are the benefits of this "Human Shadow Model"?

  • Respects Autonomy: It lets each agent have its own workspace, which leads to better development.
  • Prevents Info Overload: Keeps the focus on sharing what's truly important.
  • Enables Exploration: Encourages experimentation and trying new things without fear of broadcasting it to everyone.
  • Encourages Sharing: Makes it easy to share valuable insights and lessons.
  • Matches Human Behavior: It's natural and intuitive. It's how human developers already work!

When to Share Specific Knowledge: The Helping Hand

There are times when you should share that specific knowledge. Here's when:

  • Someone asks: If someone asks how you solved a particular problem, don't hesitate to share your detailed notes, explain your process, and help your teammate learn.
  • Pattern emerges: If, while working on a specific task, you discover a generic pattern or insight, extract that pattern and add it to LESSON_LEARNED.md. Keep the specific details private.
  • Retrospective: At the end of a retrospective, share what worked and what didn't. Don't share every single detail, but focus on the generic lessons learned.

Related

  • Issue #18 (free will philosophy): This can give you some background information on the project.
  • Cat-Lab human shadow model: The foundation of this model.
  • Cat-Lab LESSON_LEARNED.md pattern: How we implement the learning lessons.

That's the Human Shadow Model, guys! By following these patterns, you can create a more organized and efficient workflow for your team. It's all about finding the right balance between sharing and privacy, just like a human developer.