Creating Your First Decision

Creating your first decision is the foundational step in establishing a robust memory layer for your engineering organization. This process transforms abstract team agreements into enforceable constraints that guide your development lifecycle and ensure organizational judgment is preserved across time and projects. By formalizing your commitments within Hopsule, you move beyond temporary conversations and create a permanent, context-aware environment where every developer understands not just what to do, but why it must be done.

Prerequisites

Before you begin the process of creating your first decision, ensure that you have completed the following foundational steps within your organization:

• Account Access: You must have an active account with administrative or contributor permissions on the Hopsule Dashboard.

• Project Initialization: At least one project must be defined in your workspace to serve as the container for your decisions and memories.

• Context Pack Awareness: Familiarize yourself with your existing Context Packs (Capsules), as you will need to assign your decision to a specific bundle to ensure its portability.

• Hopsule CLI (Optional but Recommended): Having the Hopsule CLI installed and authenticated on your local machine allows you to verify the immediate propagation of your decision once it is accepted.

Step 1: Navigating to the Decision Management Interface

To begin, log in to the Hopsule Dashboard. On the left-hand navigation sidebar, locate and click on the Decisions tab. This view provides a comprehensive list of all existing commitments within your organization, categorized by their current lifecycle state. In the top-right corner of the interface, you will find a prominent button labeled Create Decision. Clicking this button will launch the decision creation modal, which is designed to capture all necessary metadata and context required for long-term preservation.

Step 2: Defining the Decision Core

The first section of the creation modal requires you to define the fundamental identity of the decision. This information is what developers will see first when the Hopsule for VS Code extension flags a contradiction in their workspace.

1. Title: Provide a concise, imperative title for the decision. Avoid vague language. Instead of "Thinking about logging," use "Mandatory Structured Logging for All Microservices." The title should be a clear statement of the commitment.

2. Summary: Write a brief overview (2-3 sentences) of the decision. This summary acts as the primary reference point for Hopper when it provides context to team members. It should encapsulate the "what" and the "how" of the enforcement.

3. Constraints: This is the most critical field for enforcement. Define the specific rules that must be followed. These constraints are used by the Hopsule MCP to inform AI agents and by the Hopsule IDE Extension to provide real-time warnings. For example, if the decision is about architectural patterns, list the specific forbidden patterns and the mandatory alternatives.

Step 3: Establishing Why with Memories

A decision without reasoning is merely control; a decision with reasoning is remembrance. In the Memories section of the modal, you must link the decision to the historical context that necessitated its creation. Hopsule treats memories as append-only, persistent entries that provide the "why."

You can either select existing memories from your organization's history or create a new memory entry directly within the modal. Describe the problem the team faced, the alternative solutions that were considered and rejected, and the specific lessons learned from past failures. This ensures that future team members do not revisit settled debates without new information. By linking these memories, you provide a full traceability audit trail that is accessible via the Knowledge Graph (Brain) visualization tool.

Step 4: Utilizing Hopper for Drafting Assistance

If you are unsure how to phrase a constraint or want to ensure your new decision does not conflict with existing governance, you can invoke Hopper, the built-in AI assistant, within the creation modal. Click the Ask Hopper icon to provide a natural language description of what you intend to enforce.

Hopper will analyze your organization's existing decisions and memories to:

• Suggest more precise language for your constraints.

• Identify potential contradictions with previously accepted decisions.

• Recommend relevant Context Packs based on the subject matter.

• Draft the initial rationale based on your team's historical activity feed.

Remember that Hopper is strictly advisory. It provides the draft, but the authority to finalize and accept the decision remains entirely with the human user.

Step 5: Assigning Context Packs (Capsules)

Decisions in Hopsule are designed to be portable. To ensure this decision follows the right projects and teams, you must assign it to one or more Context Packs. In the Capsules dropdown menu, select the appropriate pack. For instance, a decision regarding security protocols should be assigned to the "Global Security Standards" Capsule, while a decision about a specific API should be assigned to the "Mobile Backend" Capsule.

By grouping decisions into Capsules, you enable the Hopsule MCP to provide targeted context to AI agents depending on the specific project they are assisting with. This prevents "context bloat" and ensures that only relevant enforcement rules are active in any given session.

Step 6: Setting the Lifecycle State

Before saving, you must set the initial lifecycle state of the decision. New decisions default to the Draft state. In this state, the decision is visible within the Hopsule Dashboard but is not yet enforced via the Hopsule CLI or IDE extensions.

1. Draft: Use this for decisions that are still being refined or discussed.

2. Pending: Transition to this state when the decision is ready for formal review by team leads or stakeholders. This triggers real-time notifications to designated reviewers.

3. Accepted: Once the team reaches a consensus, move the decision to Accepted. At this moment, the decision becomes an active constraint. It will now appear in the Knowledge Graph and trigger warnings in Hopsule for VS Code.

Step 7: Verification and Enforcement

Once you have moved your decision to the Accepted state, it is important to verify its propagation across your toolchain. Open your terminal and execute the following command using the Hopsule CLI:

Your new decision should appear in the list with its unique identifier and current version number. Next, open a project associated with the assigned Context Pack in VS Code. If you write code that contradicts the constraints defined in your decision, the Hopsule IDE Extension will highlight the contradiction, providing the summary and the linked memories to remind you of the team's agreed-upon path.

Tips and Best Practices

• Be Specific, Not Verbose: Enforcement works best when constraints are clear and measurable. Avoid flowery language in the constraints field.

• Link Every Decision to a Memory: Never create a decision in a vacuum. Always provide the "why" to ensure future developers respect the governance.

• Use Versioning: If a decision needs to change, do not delete it. Create a new version. This preserves the history of how your organization's judgment has evolved.

• Leverage the Knowledge Graph: Periodically review the Brain view in the Hopsule Dashboard to see how your decisions interlink. This can help identify redundant or overly complex governance structures.

• Solo Mode is Valid: Even if you are a solo developer, creating decisions helps you maintain consistency across long-running projects and prevents "past-self" confusion.

• Review Deprecated Decisions: When a decision is no longer relevant, move it to Deprecated rather than deleting it. This keeps the memory of why that path was abandoned alive.

Troubleshooting

Related Articles

• Managing Context Packs (Capsules): Learn how to bundle decisions and memories for maximum portability across your engineering organization.

• Using Hopsule for VS Code: A deep dive into how real-time enforcement works within your development environment and how to handle contradictions.

• The Anatomy of a Memory: Understanding the append-only nature of Hopsule memories and how they provide the foundation for organizational authority.

• Advanced CLI Workflows: How to integrate Hopsule decision checks into your CI/CD pipelines to prevent non-compliant code from being merged.