Skip to content
Page 8 of 9

Challenge 1: Dark Vessel Risk Assessment Tool

What You're Starting With

From Lesson 1, you've got:

  • The Three Pillars (Scope, Intent, Structure), your framework for every prompt
  • User stories with acceptance criteria, your delegation contract format. You wrote your first one during the lesson; use it or refine it
  • The Explore → Plan → Implement → Verify workflow, your process for building iteratively
  • A project context file, created during Lesson 1's bootstrap activity. Your AI coding assistant already knows your project

Your repository is pre-seeded with data that will help you through this and future challenges. Whenever you want to know what's available, just ask your AI coding assistant. It can walk you through the data files, their structure, and how they connect to what you're building.

The Challenge

Build the core of a Dark Vessel Risk Assessment Tool: a system that ingests AIS vessel traffic data, displays the traffic picture, and screens every vessel against the OFAC sanctions list. With the shadow fleet growing from 97 vessels in 2022 to over 1,300 by 2025, the ability to quickly identify sanctioned vessels in a sea of legitimate traffic is the foundation that every other analytical capability builds on.

Your tool needs to parse the AIS data (over 40,000 messages in a nested JSON format), extract vessel identities and positions, and present them in a way that lets an analyst scan the traffic picture quickly. Then it needs to cross-reference every vessel's MMSI against the sanctions list and surface the matches. This is Challenge 1: build the traffic picture and the sanctions screening layer.

Use story-driven prompting, the delegation contracts from Lesson 1. Write a user story with acceptance criteria for each feature, delegate it, and verify the result before moving on.

It will be tempting to copy this entire challenge brief into your AI assistant and let it build everything at once. It will produce something, but you won't learn how to delegate effectively. The point of this lab is to practice giving a small, specific task with a clear definition of done, seeing how AI responds, and developing judgment about what makes a good prompt versus a vague one. That skill is what transfers to your real work, where you need AI to do something a specific way and you need to know whether it did. One-shotting a wall of requirements skips the practice that builds that judgment.

Who You're Building For

The ONI watch floor analyst. They work a 12-hour shift at the National Maritime Intelligence Center, monitoring vessel traffic across an ocean region. Their first action each shift is to scan the traffic picture and identify anything that requires attention. They need to quickly see what vessels are in their area of interest, spot any that are sanctioned, and pull up full vessel details when something warrants a closer look. Clear indicators for sanctions matches and easy access to detailed vessel records make the difference between efficient triage and wasted time.

Data Sources for This Challenge

Challenge 1 uses two data files from your repository:

  • AIS vessel traffic (ais-vessel-traffic.json): AISStream.io is a service that provides real-time AIS (Automatic Identification System) vessel tracking data via a WebSocket API. Every large commercial vessel is legally required to carry an AIS transponder that broadcasts its identity, position, speed, and destination. Your repository includes a pre-seeded snapshot of AIS messages in AISStream's format, so you don't need to sign up for an API key. In addition, we have manufactured some interesting dark vessel scenarios within this data that you may or may not encounter if using the real data stream. Ask your AI coding assistant to walk you through the data structure if you want to understand the message format.

  • OFAC sanctions list (ofac-vessels.json): The Office of Foreign Assets Control (OFAC) is a division of the US Treasury that maintains a list of sanctioned vessels, companies, and individuals that American entities are prohibited from doing business with. The Specially Designated Nationals (SDN) list is publicly available. Your repository includes a pre-seeded extract of sanctioned vessels with their MMSI numbers, names, and flag states, so you can cross-reference them against the AIS traffic data.

What to Build

Items are listed in priority order. If time is tight, focus on the items near the top first.

  • Vessel traffic display: the analyst can see all vessels and quickly understand the traffic picture. The display is populated from the pre-seeded AIS data so it works immediately.
  • OFAC sanctions screening: the analyst can quickly identify which vessels are on the OFAC sanctions list. Sanctioned vessels should stand out visually from the rest of the traffic.
  • Vessel details: when something catches the analyst's attention, they can see a vessel's full information: identity, position, movement, destination, and if sanctioned, the full OFAC entry with all known identifiers.
  • Focus area: the analyst can narrow the display to a specific maritime region or area of interest to reduce noise and focus on the vessels that matter for their watch.

These are options for teams that finish the baseline capabilities. Your team can also define your own stretch goals based on what interests you.

  • Spatial awareness: if your traffic display is text-based, consider introducing a map or other spatial representation. Seeing where vessels are relative to each other and to shipping lanes reveals patterns that a list cannot.
  • AIS message type handling: the AIS data contains two message types (PositionReport and ShipStaticData). Parsing both and connecting them gives each vessel both its current position and its full identity (call sign, IMO number, ship type, dimensions, destination).
  • Name mismatch detection: compare the vessel name broadcasting in AIS against the name in the OFAC entry for the same MMSI. A mismatch means the vessel changed its name after being sanctioned, a direct sanctions evasion indicator. Think about how this kind of intelligence fits into the analyst's workflow: how should the tool surface this finding so the analyst notices it during triage?
  • Search and sort: consider ways for the analyst to find specific vessels quickly or to surface patterns in the traffic picture (for example, stationary vessels may be conducting ship-to-ship transfers).
  • Professional styling: make the tool feel like something an analyst would trust on a watch floor, not a prototype.

Tips

  • Start with the Explore step. Before building anything, explore both the domain and the data. Ask your AI coding assistant about the user's workflow: "What does a maritime intelligence analyst's daily routine look like? What are they watching for when they scan vessel traffic?" Then explore the data: "Parse the AIS file and show me what one vessel's data looks like." Understanding both the user and the data structure will help you build something useful, not just functional.
  • Use the story you wrote in Lesson 1. You already have a delegation contract ready to go. Hand it to your AI coding assistant. Verify the result against your acceptance criteria. Then write the next story.
  • MMSI connects your data sources. The MMSI (Maritime Mobile Service Identity) is a unique 9-digit number assigned to each vessel's transponder. You can use it to match a vessel in the AIS traffic data against the same vessel in the OFAC sanctions list. Use MMSI for matching, not the vessel name, because sanctioned vessels frequently change their names.
  • Your first feature sets the pattern. You're starting from scratch, and AI will make structural choices with your first feature that every future feature builds on. After it's working, ask AI: "Walk me through how you organized this: the file structure, the components, how data flows. Would this structure hold up well as we add more features?" If AI suggests a better organization, now is the cheapest time to reshape it.
  • Save & Sync after each working feature. Build the habit now. Every time something works, run Save & Sync. You'll thank yourself later when you want to undo a change that breaks something. Remember: your AI assistant starts fresh every conversation. Your saved, synced code is the only thing that persists.
  • If AI breaks something, undo and retry. Your AI assistant will often catch errors and try to fix them on its own. But if the app is broken or the output is completely wrong, you can always say: "Undo everything you just changed." Then start a fresh conversation and re-delegate with a more specific story and tighter acceptance criteria. A broken result is feedback on your delegation, not a verdict on the approach.
  • Start fresh between features. After completing and verifying a feature, start a fresh conversation to reset your context. Your project context file loads automatically, so every fresh conversation starts productive. This prevents quality from fading as the conversation grows.