Gentleman-Skills Documentation

When working with Angular forms, select your approach based on your application's requirements and stability needs:

• Signal Forms (v21+, experimental): Recommended for new applications leveraging Angular Signals. Provides automatic two-way binding, type-safe field access, and schema-based validation.
• Reactive Forms (production): The stable, recommended choice for production applications. These are synchronous and easier to test.
• Template-driven Forms: Suitable for very simple forms where complex logic or validation is not required.

In Elixir, expected failures (e.g., user not found, validation errors) should be returned as values (typically {:error, reason}) rather than raising exceptions. Using raise for business logic hides error cases from @spec, forces non-idiomatic try/rescue blocks, and treats expected failures as unexpected crashes.

Correct Pattern: Return tagged tuples like {:ok, result} or {:error, reason} to allow the caller to handle the error using pattern matching.

# ❌ BAD - Crashes on expected error
def fetch_user(id) do
  Repo.get(User, id) || raise "User not found"
end

# ✅ CORRECT - Return error as a value
def fetch_user(id) do
  case Repo.get(User, id) do
    nil -> {:error, :not_found}
    user -> {:ok, user}
  end
end

In the App Router, components are Server Components by default. You do not need a directive to make them server-side. They can be async functions, allowing you to fetch data directly within the component body.

// No directive needed - async by default
export default async function Page() {
  const data = await db.query();
  return <Component data={data} />;
}

Do not use .component, .service, or .model suffixes in filenames. The folder context provides the necessary information.

Examples:

• Use user-profile.ts instead of user-profile.component.ts.
• Use cart.ts instead of cart.service.ts.
• Use user.ts instead of user.model.ts.

When using the Jira MCP to update an epic's description, you must not use Markdown. Instead, use Jira Wiki markup for the customfield_10363 (Work Item Description) field to ensure correct rendering in the Jira UI.

Wiki Markup Mapping

• Headings: Use h2. instead of ##.
• Bold: Use *text* instead of **text**.
• Bullets: Use * item for bullets and ** subitem for nested bullets.

Example Payload for customfield_10363

{
  "customfield_10363": "h2. Feature Overview\n\n{overview}\n\nh2. Requirements\n\n*{Section 1}*\n* {requirement 1}\n\nh2. Technical Considerations\n\n*Performance:*\n* {consideration 1}"
}

Every test case should assert an expected outcome. A test that simply calls a function without using assert (or similar) does not actually verify behavior and can pass even if the code is broken.

# ✅ CORRECT - Assert expected behavior
test "creates user successfully" do
  assert {:ok, user} = UserService.create_user(%{name: "Juan"})
  assert user.name == "Juan"
end

For scalable mobile applications, follow a modular directory structure. A recommended pattern separates routing, reusable UI, feature logic, and global state:

src/
├── app/                    # Expo Router screens (if using)
│   ├── (tabs)/            # Tab navigator group
│   ├── (auth)/            # Auth flow group
│   └── _layout.tsx        # Root layout
├── components/
│   ├── ui/                # Reusable UI components
│   └── features/          # Feature-specific components
├── hooks/                 # Custom hooks
├── services/              # API and external services
├── stores/                # State management (Zustand)
├── utils/                 # Utility functions
├── constants/             # App constants, themes
└── types/                 # TypeScript types

Pure functions should only perform computations and should not have side effects like logging or database calls. Including I/O in pure functions makes them difficult to test, as you must mock the I/O or capture logs to verify behavior.

# ❌ BAD - Logger call in calculation
def calculate_total(items) do
  total = Enum.reduce(items, 0, &(&1.price + &2))
  Logger.info("Total: #{total}")  # Side effect!
  total
end

Chaining more than 4 steps in a with block violates the Single Responsibility Principle and makes the code hard to read. If you have a long chain of operations, group related steps into cohesive, named functions to simplify the main flow.

# ❌ BAD - Too many responsibilities
with {:ok, a} <- step1(),
     {:ok, b} <- step2(a),
     {:ok, c} <- step3(b),
     {:ok, d} <- step4(c),
     {:ok, e} <- step5(d),
     {:ok, f} <- step6(e) do
  {:ok, f}
end

# ✅ CORRECT - Group into cohesive functions
with {:ok, validated} <- validate_and_fetch(id),
     {:ok, processed} <- process_business_rules(validated),
     {:ok, result} <- persist_and_notify(processed) do
  {:ok, result}
end