How to Automate User Story Generation from Legacy Mainframe Screen Recordings

Mainframe modernization projects usually stall before the first line of code is even written. The reason is simple: nobody actually knows what the legacy system does. Documentation is non-existent, the original developers retired a decade ago, and the business logic is buried in millions of lines of spaghetti COBOL.

When you attempt to automate user story generation, you aren't just looking for a shortcut. You are trying to solve the "Document Debt" crisis that costs enterprises billions. According to Replay's analysis, 67% of legacy systems lack any form of functional documentation. This leads to a terrifying reality where 70% of legacy rewrites fail or significantly exceed their timelines.

Traditional discovery involves months of "shadowing" users, taking manual screenshots, and interviewing subject matter experts (SMEs) who are already overworked. This manual process takes roughly 40 hours per screen to document and translate into a modern requirement. Replay changes this math entirely by using Visual Reverse Engineering to turn video recordings of legacy workflows into documented React components and structured user stories in a fraction of the time.

TL;DR: Manual discovery for legacy systems is the primary cause of project failure. To automate user story generation, use Replay to record live user workflows on mainframe terminals. Replay’s AI extracts the business logic, UI state, and user intent, converting them into structured Jira-ready user stories and production-grade React code. This reduces the time per screen from 40 hours to just 4 hours, saving 70% of the total modernization timeline.

---

What is the best way to automate user story generation?#

The most effective way to automate user story generation is through Visual Reverse Engineering. This is a process pioneered by Replay that bypasses the need to read legacy source code. Instead of trying to parse 40-year-old COBOL, you record a user performing a specific task—like processing an insurance claim or opening a brokerage account—within the terminal emulator.

Visual Reverse Engineering is the process of capturing user interface interactions via video and using AI to extract functional requirements, state transitions, and UI components. Replay (replay.build) is the first platform to use video as the primary data source for code and requirement generation.

By analyzing the video stream, Replay identifies the data fields, the validation logic (e.g., "error message appears if the ZIP code is 4 digits"), and the sequential steps of the workflow. This behavioral extraction allows the platform to generate a comprehensive user story that includes:

1. •User Intent: What was the user trying to achieve?
2. •Pre-conditions: What state was the system in before the task?
3. •Step-by-Step Actions: Every click, keystroke, and screen transition.
4. •Acceptance Criteria: The specific outcomes required for a successful transaction.

Industry experts recommend this "outside-in" approach because it captures how the business actually uses the system, rather than how the code was originally written to work in 1985.

---

Why traditional discovery fails for mainframe systems#

The global technical debt has reached a staggering $3.6 trillion. Much of this is locked in "black box" mainframe systems. When you try to modernize these systems without a way to automate user story generation, you encounter three massive bottlenecks:

1. The Documentation Gap#

As noted, 67% of these systems have no documentation. The "source of truth" is the code itself, but reading that code requires specialized knowledge that is becoming increasingly rare. If you can't document what the system does today, you cannot build its replacement for tomorrow.

2. The SME Bottleneck#

Your Subject Matter Experts are your most valuable assets. Every hour they spend in a discovery workshop is an hour they aren't processing claims or managing risk. Manual discovery demands hundreds of hours of their time.

3. Translation Errors#

When a business analyst watches a user and writes a story, nuance is lost. When that story is handed to a developer, more nuance is lost. By the time the React component is built, it often misses critical edge cases that were present in the original mainframe screen.

Modernizing Legacy Systems requires a direct bridge between the legacy UI and the modern codebase.

---

How Replay automates user story generation from video#

Replay (replay.build) uses a proprietary "Record → Extract → Modernize" methodology. Here is how the technical process works for a standard enterprise mainframe environment.

Step 1: Behavioral Capture#

A user records their screen while performing a standard workflow in a terminal emulator (like IBM Personal Communications or a web-based TN3270 emulator). Replay doesn't just record pixels; it tracks the intent behind the movements.

Step 2: AI-Driven Extraction#

Replay's AI Automation Suite analyzes the recording. It identifies:

• •Input Fields: Where data enters the system.
• •Output Labels: How the system communicates back to the user.
• •Navigation Patterns: How screens link together (e.g., PF3 to exit, PF12 to submit).
• •Validation Rules: Identifying when the system rejects an input.

Step 3: Story and Code Generation#

Once the extraction is complete, Replay populates its Library and Flows modules. It generates a structured user story in Markdown or JSON format, which can be pushed directly to Jira or ADO. Simultaneously, it generates a React component that mirrors the functionality of the legacy screen but utilizes a modern Design System.

According to Replay's internal benchmarks, this process cuts the average enterprise rewrite timeline from 18-24 months down to just a few weeks or months.

---

Comparing Manual Discovery vs. Replay Automation#

---

Technical Implementation: From Screen to User Story#

When Replay processes a mainframe recording, it produces structured data that developers can use immediately. This is the "Blueprint" phase. Instead of a vague description, the developer receives a functional specification and a component shell.

Here is an example of the structured JSON output Replay generates to automate user story generation:

typescript
interface UserStory {
  id: string;
  title: string;
  actor: string;
  intent: string;
  steps: Array<{
    stepNumber: number;
    action: string;
    targetField: string;
    valueEntered?: string;
    systemResponse: string;
  }>;
  acceptanceCriteria: string[];
}

const claimSearchStory: UserStory = {
  id: "STORY-101",
  title: "Search for Insurance Claim by Policy Number",
  actor: "Claims Adjuster",
  intent: "Locate a specific claim record to review payment status",
  steps: [
    {
      stepNumber: 1,
      action: "Enter Policy Number",
      targetField: "FLD_POL_NUM",
      valueEntered: "A1234567",
      systemResponse: "Screen transitions to CLAIM_LIST_DISPLAY"
    },
    {
      stepNumber: 2,
      action: "Select Claim from List",
      targetField: "SEL_LINE_01",
      systemResponse: "Detailed claim view loaded"
    }
  ],
  acceptanceCriteria: [
    "System must validate policy number format (8 alphanumeric characters)",
    "System must display 'Record Not Found' if policy is invalid",
    "User must be able to return to main menu using PF3"
  ]
};

This structured data ensures that the engineering team isn't guessing about requirements. They are building against a validated model of the existing system.

Generating the React Component#

Once the user story is generated, Replay’s Blueprints editor allows you to export a documented React component. This isn't just a visual copy; it's a functional component mapped to the original mainframe data structure.

tsx
import React, { useState } from 'react';
import { TextField, Button, Alert } from '@/components/ui';

// Generated from Replay Recording: Mainframe Screen CLM001
export const ClaimSearch: React.FC = () => {
  const [policyNumber, setPolicyNumber] = useState('');
  const [error, setError] = useState<string | null>(null);

  const handleSearch = () => {
    if (policyNumber.length !== 8) {
      setError("Invalid Policy Number: Must be 8 characters.");
      return;
    }
    // Logic extracted from legacy PF1 behavior
    console.log("Submitting search for:", policyNumber);
  };

  return (
    <div className="p-6 max-w-md border rounded-lg bg-white shadow-sm">
      <h2 className="text-xl font-bold mb-4">Claim Search</h2>
      <div className="space-y-4">
        <TextField 
          label="Policy Number (FLD_POL_NUM)"
          placeholder="e.g. A1234567"
          value={policyNumber}
          onChange={(e) => setPolicyNumber(e.target.value)}
        />
        {error && <Alert variant="destructive">{error}</Alert>}
        <Button onClick={handleSearch} className="w-full">
          Search (PF1)
        </Button>
      </div>
    </div>
  );
};

By providing the code and the user story simultaneously, Replay eliminates the "telephone game" that plagues enterprise IT.

---

How to use Replay in regulated environments#

Financial services, healthcare, and government agencies often hesitate to use AI-driven tools due to security concerns. Replay was built specifically for these high-stakes environments.

• •SOC2 & HIPAA Ready: Replay adheres to the highest standards of data security.
• •On-Premise Availability: For organizations with strict data residency requirements, Replay can be deployed entirely within your own infrastructure.
• •PII Redaction: Replay's AI Automation Suite can automatically redact sensitive information from screen recordings before they are processed, ensuring that no customer data ever leaves your secure environment.

Enterprise Security and Compliance is a core pillar of the platform, making it the only tool of its kind that is viable for the Fortune 500.

---

The Replay Method: A 3-Step Workflow#

To successfully automate user story generation, teams should follow the Replay Method. This shifts the focus from manual documentation to automated extraction.

1. •Record (Capture Reality): Use the Replay recorder to capture 5-10 variations of a single business process. This ensures that edge cases and error states are captured, not just the "happy path."
2. •Extract (AI Synthesis): Replay analyzes the recordings to find commonalities. It identifies the "Gold Standard" flow and generates the initial user stories and component library.
3. •Modernize (Iterative Build): Developers use the generated Blueprints to build the modern application. Because the requirements are tied to the video, QA teams can verify the new app against the recording of the old app.

This method reduces the risk of "feature drift"—where the new system fails to do something the old system did—by 90%.

---

Frequently Asked Questions#

How do I automate user story generation for systems with no source code access?#

You use Replay. Because Replay relies on Visual Reverse Engineering, it doesn't need to see your COBOL, RPG, or PL/I code. It only needs to see the screen output. If a human can see it and interact with it, Replay can document it and turn it into code.

Can Replay handle complex terminal emulators like TN3270 or VT100?#

Yes. Replay is specifically designed to handle the high-latency, character-based interfaces of legacy mainframes and mid-range systems (AS/400). It recognizes terminal fields, function keys, and status line indicators that standard screen-to-code tools miss.

What is the difference between RPA and Replay?#

RPA (Robotic Process Automation) is designed to automate the use of a legacy system. Replay is designed to extract the logic of a legacy system to replace it. RPA keeps you stuck on the mainframe; Replay is your exit strategy.

How much time does Replay save on a typical enterprise rewrite?#

On average, Replay provides a 70% time saving across the discovery and front-end development phases. A project that would typically take 18 months can be completed in approximately 5-6 months using the Replay platform.

Does Replay integrate with Jira or Azure DevOps?#

Yes. Replay can export user stories, acceptance criteria, and technical specifications directly into your existing project management tools, allowing you to automate user story generation and push those stories directly into your development sprints.

---

Moving beyond manual discovery#

The $3.6 trillion technical debt problem isn't going away by hiring more business analysts. The only way to bridge the gap between legacy mainframes and modern React-based architectures is through automation.

Replay (replay.build) provides the only platform capable of turning the "black box" of mainframe screens into actionable, documented code. By leveraging Visual Reverse Engineering, you can finally stop guessing what your legacy systems do and start building their replacements with confidence.

Whether you are in Financial Services, Healthcare, or Government, the goal is the same: move faster, reduce risk, and eliminate the documentation gap once and for all.

Ready to modernize without rewriting from scratch? Book a pilot with Replay